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

[Thomas Schraitle <tom_schr@web.de>]

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 this
> 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 writing 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 improving
the schema. The XSLT 1.0 stylesheets received 5 issues and 1 PR. Not counted
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 grow
and be successful. I will certainly continue to add issues and pull requests in
the future whenever I have time.


> May be good start would be if you will specifically list feature that you 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 "not
  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 is
  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 different
  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.


--
GruÃ/Regards
  Thomas Schraitle