Re: State of topic oriented writing in DocBook?

Hi Jirka,

thanks for your response. :)

On 30.11.22 15:11, Jirka Kosek wrote:
> On 30.11.2022 10:49, Thomas Schraitle wrote:
>> 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 think that one of the reasons that topic oriented authoring is not 100=
%
> perfect in DocBook is that many core DocBook developers are not using th=
is
> feature on their own projects.

Well, maybe they'd better get started? ;)

Seriously, this is hardly noticeable in ordinary documents that use books =
or
articles. You will run into issues once you switch to topic oriented writi=
ng or
if you use some of the more modern features.


> So unless there is report of missing or broken
> functionality there is no push to improve situation.

I did.

In the last years I've filed 13 issues in the docbook repo alone for impro=
ving
the schema. The XSLT 1.0 stylesheets received 5 issues and 1 PR. Not count=
ed
are issues before moving from Sourceforge to GitHub. If I count the mails
written to this mailinglist and docbook-apps it should be over 500...

All in all you can say, I care about DocBook. :-) I want this project to g=
row
and be successful. I will certainly continue to add issues and pull reques=
ts in
the future whenever I have time.


> May be good start would be if you will specifically list feature that yo=
u are
> missing or that are broken in some tool.

Those were the points that come to mind off the top of my head:

* Support for conrefs and keymaps
   This is a feature from DITA and as far as I know, this is currently "no=
t
   possible". I don't mean any workarounds, I mean something officially
   blessed by the technical committee AND supported by the DocBook schema
   AND stylesheets.
   Certainly there are more features that could be implemented, but this i=
s
   what I miss most in DocBook.

* Restrictive handling of attributes from different namespaces
   It's probably a design decision in the DocBook schema and to some
   degree it makes sense. The solution would probably be to write a
   DocBook customization and be happy.
   However, not everybody wants to write a customization layer or
   has the expertise to do so.
   Certainly, this is a minor issue. But sometimes I run into
   situation were the common attributes has some limitations and
   it would be helpful that DocBook would just ignore this foreign
   attribute.

   Would it be really that bad if DocBook could just ignore attributes
   from foreign namespaces?

* Assemble process isn't feature complete
   The assemble elements <filterout>, <filterin>, <transforms>, and
   <relationships> aren't supported yet.

* The <topic> element
   You can't nest it. This makes it less useful to mix and match
   topics.
   The <section> element has this ability, however, it brings
   semantic baggage whereas <topic> is a general-purpose container.

   If I may make a bold wish: why not allow <topic> as a general
   division element on ALL levels? Why restrict its use as the
   TDG advertises it already as a "general-purpose container"?

* Extended XLinks aren't supported in the XSLT 1.0 stylesheets
   Only simple 1:1 links are supported, not 1:n links. However, this is
   implemented in the XSLT 3.0 stylesheets. Which is another topic, see
   below.

* Some unsupported elements in XSLT 1.0 stylesheets
   Last time, I had issues with <topic>, <result> and some newer
   ones were added by DocBook 5.2.

* ID fixup from the transclusion mechanism
   If I remember, Bob once said, there are many ways to do it and differen=
t
   people have different use case. That's certainly correct, but wouldn't
   it be nice to start with at least one way and let people customize it, =
if
   they needed it? That's how the DocBook schema and the stylesheet work,
   so why not provide such a solution?

* XSLT 1.0 vs XSLT 3.0 and support
   Currently, we have the stable XSLT 1.0 stylesheets which supports a
   broad range of output formats. It seems, the trend goes towards XSLT 3.=
0,
   but that version doesn't support FO, only HTML5.
   I'm absolutely sure, XSLT 3.0 will give us many cool ways to deal with
   DocBook. However, not everybody can switch to the new version yet.
   Plus we are "limited" to Saxon{9,10,11} as there is no other open
   source processor for XSLT 3.0 yet.

   I'm worried that every new DocBook feature will be included only in
   the XSLT 3.0 stylesheets and the XSLT 1.0 stylesheets will be left out.


If I remember more, I can amend this list.

Hope that helps a bit.


=2D-
Gru=C3=9F/Regards
   Thomas Schraitle