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

[Thomas Schraitle]

Hi,

On 30.11.22 15:25, Jean-Christophe Helary wrote:

[...]
I can see how linking to such IDs form other parts could be non-trivial, but 
conversely, I don't see the point of trying to link to an ID that will be 
included in multiple places in a document, so maybe the point is moot.


Jirka explained the transclusion mechanism already.

The linking from one part of a document into another one is already solved by
DITA. I don't know all of it, but from what I saw it is way more advanced than
DocBook's approach.

I would really love to see a similar feature coming to DocBook.

--
Gruß/Regards
  Thomas Schraitle


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

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

[Thomas Schraitle]

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 , , , and
   aren't supported yet.

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

  If I may make a bold wish: why not allow  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 ,  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


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

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

[Thomas Schraitle]

Hi Peter,

thank you for your response. :-)

On 30.11.22 13:56, Peter Desjardins wrote:


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.


Great, I'm not alone. :-D



[...] Maybe I should
put my goal for unique IDs using transform in an official GitHub issue
?


Yes, that would be the official repo.


--
Gruß/Regards
  Thomas Schraitle


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

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

[Jean-Christophe Helary]

> On Nov 30, 2022, at 23:42, Jirka Kosek  wrote:
> 
> On 30.11.2022 15:25, Jean-Christophe Helary wrote:
>> It seems to me that there could be a mechanism where xi:include manages 
>> included IDs by generating some kind of "name space" over the whole 
>> document, maybe based on the "includee" part ID.
>> I can see how linking to such IDs form other parts could be non-trivial, but 
>> conversely, I don't see the point of trying to link to an ID that will be 
>> included in multiple places in a document, so maybe the point is moot.
> 
> Well this is already supported by XInclude and transclusion mechanism, see:
> 
> https://docbook.org/docs/transclusion/transclusion.html#ex.6
> 
> xslTNG support this mechanism, when enabled by the following option:
> 
> https://xsltng.docbook.org/guide/p_docbook-transclusion.html
> 
> Does this solve your use-case?

It will solve it the moment I understand how to set that.

If I had known that what I'm looking for is called "transclusion" I would 
certainly have investigated this solution way before, but better late than 
never :-)


-- 
Jean-Christophe Helary @jchel...@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/


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

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

[Jirka Kosek]

On 30.11.2022 15:25, Jean-Christophe Helary wrote:

It seems to me that there could be a mechanism where xi:include manages included IDs by generating 
some kind of "name space" over the whole document, maybe based on the 
"includee" part ID.

I can see how linking to such IDs form other parts could be non-trivial, but 
conversely, I don't see the point of trying to link to an ID that will be 
included in multiple places in a document, so maybe the point is moot.


Well this is already supported by XInclude and transclusion mechanism, see:

https://docbook.org/docs/transclusion/transclusion.html#ex.6

xslTNG support this mechanism, when enabled by the following option:

https://xsltng.docbook.org/guide/p_docbook-transclusion.html

Does this solve your use-case?


--
--
  Jirka Kosek  e-mail: ji...@kosek.cz  http://xmlguru.cz
--
 Professional XML and Web consulting and training services
DocBook/DITA customization, custom XSLT/XSL-FO document processing
--
Bringing you XML Prague conferencehttp://xmlprague.cz
--


OpenPGP_signature
Description: OpenPGP digital signature

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

[Jean-Christophe Helary]

> On Nov 30, 2022, at 23: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. So unless there is report of missing or broken 
> functionality there is no push to improve situation.
> 
> May be good start would be if you will specifically list feature that you are 
> missing or that are broken in some tool.

It seems to me that there could be a mechanism where xi:include manages 
included IDs by generating some kind of "name space" over the whole document, 
maybe based on the "includee" part ID.

I can see how linking to such IDs form other parts could be non-trivial, but 
conversely, I don't see the point of trying to link to an ID that will be 
included in multiple places in a document, so maybe the point is moot.



-- 
Jean-Christophe Helary @jchel...@emacs.ch
https://traductaire-libre.org
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/


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

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

[Jirka Kosek]

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. So unless there is report of 
missing or broken functionality there is no push to improve situation.


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


Jirka

--
--
  Jirka Kosek  e-mail: ji...@kosek.cz  http://xmlguru.cz
--
 Professional XML and Web consulting and training services
DocBook/DITA customization, custom XSLT/XSL-FO document processing
--
Bringing you XML Prague conferencehttp://xmlprague.cz
--


OpenPGP_signature
Description: OpenPGP digital signature

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

[Peter Desjardins]

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/msg5.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
<https://github.com/docbook/xslt10-stylesheets/issues>?

Peter

On Wed, Nov 30, 2022 at 4:50 AM Thomas Schraitle  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, 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-unsubscr...@lists.oasis-open.org
> For additional commands, e-mail: docbook-h...@lists.oasis-open.org
>
>

[docbook] State of topic oriented writing in DocBook?

[Thomas Schraitle]

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, 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-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-h...@lists.oasis-open.org