search

openSUSE / daps

DocBook Authoring and Publishing Suite (DAPS)
https://openSUSE.github.io/daps
Other
62 stars 19 forks source link

Support Assembly Files [sf#164] #163

Closed tomschr closed 1 year ago

tomschr commented 9 years ago

Reported by tom_schr on 2013-07-03 10:47 UTC DocBook 5.1 and beyond knows Assemblies. This assembly file should be supported by DAPS to support the more topic oriented approach.

From the TDG, Chapter 6 Assemblies:

One modern school of thought on technical documentation stresses the development of independent units of documentation, often called topics, rather than a single narrative. Instead of writing something that DocBook users would easily recognize as a book consisting of a preface, several consecutive chapters, and a few appendixes, the author (or authors) write a set of discrete topics covering different aspects of the system as if they were wholly independent. [...] In a successful deployment, you might find a library of say 1,000 topics which, taken together, document five or six related systems, each of which uses 700-800 topics. Some topics are used in every system, many are used in several systems, and a small number of topics are unique to a specific system. In order to make such a documentation platform functional, you need not only the individual topics, but also some sort of “map” or “assembly” file that describes which topics from the library are used, what relationships exist between them and, at least for print presentation, what linear order should be imposed upon them.

An assembly file can be created automatically or manually. Currently the best way is to start from an existing document (book or article) and apply a XSLT stylesheet as described in Splitting DocBook 5 Documents Into Topics.

An assembly file is comprised of the assembly element which can contain elements about the resources, structure, relationships between resources, and even transformations. At the moment (July 2013), transformations are not supported. Basic assemblies with resources and structures are possible though.

Once an assembly file is created (manually or automatically), the complete document is created by an assemble stylesheet as described in Assembling Topics.

tomschr commented 9 years ago

Commented by tom_schr on 2013-12-03 09:19 Something for a DocBook5 user guide?

fsundermeyer commented 1 year ago

Fixed with 05fcf7c71eb and subsequent commits