Document Build Process and How to Use It

[tomschr]

Although this repository contains some readme files, it's quite hard to wrap the head around it. :smile:

I fear, even for a dedicated DocBook user, a lot of things are still unclear. In comparison to the XSLT1.0 stylesheets, it seems much more complicated (maybe it isn't, but it's a first impression). You can't clone this repository and "just start".

As such, I would be happy to see more additions to documentation. Maybe it can be splitted into two topics: something developer related and something for the end user.

IMHO, these topics should be covered in more depth:

Developer

• What requirements are needed?
  Both to build the stylesheets and what dependendies are needed to use/run it
• How to build the stylesheets
  It seems, it is not possible to just clone this repo and start out of the box. A step by step instructions would help a lot.
• How to customize the build process?
  In case, someone has to adapt the process to build packages for major Linux distributions or other platforms.

  End User

• How to use the stylesheets?
  It is unclear how to use the stylesheets: Should the users run Saxon9 or java -jar docbook-xslt2-VER.jar?
• How can I integrate customization layer(s)?
  In contrast to the old stylesheets, there are more official stages (or cleanup steps). How do they relate and how can I change/adapt them? How to include my customization layer?
• How is the intended workflow?
  I think, how the stylesheets are used with or without any XProc pipelines needs some clarifications. Is it useful to just transform a DocBook XML file with the stylesheets? Or is the transformation broader and the user has to take XProp pipelines into account?

Thanks for this great work! Let the world know how to use it.

[ndw]

Yes, I agree. I'm also working on a "getting started" repo that just works out of the box.

[tomschr]

Great! Thanks a lot! :+1: