Re: [docbook] State of topic oriented writing in DocBook?

[Peter Desjardins <peter.desjardins.us@gmail.com>]

Hello, Thomas!

My team uses DocBook topics and the assembly file. We combine modules in our structure elements to get the output that we need, but I agree that the implementation needs to support more flexible combinations of modules.

My understanding of the situation is that the design for assembly structure and module elements allows for very flexible topic-based authoring, but that there are important features that are still not implemented. (I am sure I could be misunderstanding the standard design intention!) For example, I asked this question about making IDs unique using the transform element:

https://lists.oasis-open.org/archives/docbook-apps/202201/msg00005.html

I am very interested in contributing to implementation of more assembly features to support flexible topic-based authoring. I'm glad you brought this up! It might be useful to identify some high-priority assembly features that your team needs so we could focus any interested contributors. Maybe I should put my goal for unique IDs using transform in an official GitHub issue?

Peter

On Wed, Nov 30, 2022 at 4:50 AM Thomas Schraitle <tom_schr@web.de> wrote:

Hi,

as the documentation world uses more and more a topic-oriented approach,
solutions are being sought that do justice to this approach. Also for DocBook.

As DocBook wants also be part of that idea, it created assemblies which is
good. On the other side it seems it is only partly prepared for such an
approach. Especially if we compare it to DITA, TEI, and others.

One example is the use of XIncludes which is great. It allows to include
content from other files. We can even include such content twice. However, it
only works if we not have IDs twice otherwise we get duplicate ID errors.

We can use transclusion attributes or an assembly file which makes it easier to
write topics and combine them. On the other side, it can be hard to write and
maybe it does not cover all use cases.

Sooo... I gives me the impression we still aren't fully there: DITA has
conrefs, keymaps, and other fancy issues. Certainly not all are needed, but
these are one of the things that lacks DocBook. Or am I missing them?

To make a long story short: how is the current state of topic oriented writing
in DocBook? What's still missing in the DocBook schema and the stylesheets?
What is DocBook willing to support? Can some DITA features be replicated in
DocBook (like the mentioned conref and keymaps)?

For example, we are trying to move our documentation to a more topic oriented
approach. We don't want to move to DITA as all of our writers know DocBook. We
aren't fully there yet, but would like to continue with our existing DocBook
toolchain. Would like to mix our topics and have an assembly for creating the
result. Unfortunately, <topic>s can't be nested. ID fixup is another issue,
it's not really supported yet.

It's sometimes frustrating to see that DocBook is halfway there but is missing
this extra mile that you need. I would really like to see solutions in DocBook
that supports a more topic oriented writing experience.

I hope it doesn't sounds too negative. :) I intentionally focused in this
e-mail on a more high-level overview to not bore you to death with details and
keep this post short. ;)

So what's your take on this? How do you use DocBook for an topic oriented
approach? Are you happy? What are you missing? Am I wrong?

Thanks for your thoughts. :-)

--
GruÃ/Regards
 ÂThomas Schraitle

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org