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/
