Re: [docbook-apps] DocBook customisation for "generic business documents"?

[Frank Steimke <f-steimke@berger-und-steimke.de>]

Hi Paul,

i think we have something similar. We use a DocBook base solution for contracts with our partners. In short:

Customization of Relax NG Schema and Schematron

• Reduce the possible Elements (e. g. only CALS Tables, HTML Tables are not allowed). No Synopsis elements and so on. Reduce to a small subset, it will help in later steps (see "negotiation").
  
• Add additional Elements, like contract number, contract status. Some of them are mandatory, some optional.
• Use Relax NG for Datatyping of these new Elements (all contract numbers must follow some pattern)
  
• Use the @role Attribute to qualify sections, e. g. "overall-goal".
• Use schematron for business rules, e. g. "If status is proposal or final, there must be exactly one section qualified as overall-goal"

Optional: Use Oxygen CSS extensions for Forms

Optional: Use advanced mechanism to access external ressources

• ÂÂÂ e. g. an XML "Database" of budget for departments in our company.
  

Write some stylesheets for a transformation in DocBook 5.1 (original)

• Additional elements will be transformed into appropriate DocBook constructs
• A informaltable with contract Metadata will be generated at the start of the Document
• Result is a Document, which is valid with respect to DocBook 5.1 schema (Relax and Schematron)
  

Optional: customization of DocBook HTML or XSL-FO Stylesheets for publishing.

• A special layout for contracts
  

We use this solution with success since some years. We have a simple "Template for contracts". Authors are free to use many of the regular DocBook mechanism in contracts, but are forced to follow a general structure for this type of document, and to add contract metadata. A contract without a section for the overall goal is invalid. Schematron allows different rules for different document status (e. g. a missing contract number is a warning for draft documents, but an error for proposal or final). We are able to query a collection of contract documents (e. g. "total sum of contract value in a defined period of time") with simple XSLT mechanism.

The only drawback is the process of negotiation of contracts, since DocBook stylesheets in the standard Distribution can produce HTML or PDF, but our Partner would like to have editable Documents in MS Word. We have tested three solutions:

1. Ask them to edit structured Documents (DocBook customization for contracts): No way. They are all IT-professionals, but working with a Document on a computer means MS Word and nothing else to them
   
2. Poor mans generation of MS-Word: use standard stylesheet to generate HTML, Use the HTML import mechanism of MS Word to greate .docx. Works for most DocBook Elements. Exceptions are Footnotes, Table column width, wrong ratio in images and so on
3. Transformation from DocBook to Open Document Format (ODF 1.2): This is possible, because we have a restricted set of DocBook Elements.

"DocBook for contracts" was our first application, but i have applied the same idea to other topics with success.

Frank Steimke
KoSIT
http://www.xoev.de

Am 29.07.2020 um 04:51 schrieb Paul Hoadley:

Hello,

We have used DocBook in the past for technical documentation with great success, but we currently have a use case involving generation of what you might call "generic business documents"âe.g., "policies", "procedures", "checklists", and so on.

The client supplies us with "templates" for these documents, which then need to be modified based on various end-user data. (This can be as simple as, say, substituting an organisation's name in a title, but extends right up to conditional inclusion or exclusion of paragraphs and table rows, as well as, say, populating lists with user-supplied values.) At the moment we have a prototype solution involving Word documents as the source (manipulated with Apache POI), but it's very brittle, as Word is utterly unsuited as the source format. This all seems ripe for an XML-based solution.

My question for the list is simple: has anyone used DocBook to mark up this kind of "generic business document"? I have no doubt it would work, and the existing stylesheets with a customisation layer makes a very attractive starting point. If anyone has any success stories (or otherwise!), or advice, I'd love to hear them.

--Â
Paul Hoadley
https://logicsquad.net/
https://www.linkedin.com/company/logic-squad/