Larry, your use case is in sync with the ones I have. I look forward to
reviewing your sample files.
--
Gershon
Original Message-----
From: Rowland, Larry [mailto:larry.rowland@hp.com]
Sent: Tuesday, July 13, 2010 6:19 PM
To: Norman Walsh; docbook-tc@lists.oasis-open.org
Subject: RE: [docbook-tc] Assembly questions
I actually have a concrete example that I can explain (hopefully). It
would take some time to generate a smaller, example size version of it,
but here is a high-level description of it.
We produce help systems that are essentially our implementation of a
Webhelp system (developed completely independently at about the same
time). The delivery environment is an Apache Tomcat system that the
documented products use for delivery a Web-based GUI. A CGI system
associates topic IDs with Web pages generated by the help system.
Each page of the help system is represented by an XML source file.
A structure file represents the hierarchical relationships among the
help nodes (this is what I am looking at using the assembly for in the
future). We use Namazu for a search engine, running on the server.
Because it is a help system, the processing system knows it needs to do
the following:
- load the structure
- build some auxiliary files to simplify later production
stages
- generate a table of contents page for the system
- process each of the help node source files into a result file,
with a static, navigable hierarchy of the help system in a div
on the left hand side of the HTML page being rendered.
- parse each help node file looking for entryPoint elements to
build a map.properties file that relates the help topic IDs to
the URI for that page (or section on the page) associated with
that topic ID.
- generate an index page for the system.
- generate the inverse index files that are used by Namazu for
search.
- copy the graphics files into the destination directory for the
Rendered HTML.
- generate the printable version of the help system.
This is handled by using the build.all target in an Ant build file that
identifies the project as a help system. Having a type would allow this
information to be carried in the document instead of in the build file
associated with the project. We use a file- per-file model to allow for
simple control of file names in the resulting output, since we are
frequently replacing an established set of files in a source tree and
the map.properties file is not always used by our partners in the lab.
We have also found that the model of "one file = one topic" makes it
easier for the authors to break out of the linear narrative model that a
single file tends to lead to (reinforcing the preferred cognitive model
can be an important part of usability for tools).
As mentioned above, we generate a printable version of the help system.
This is a separate target in the build file (that is also used build.all
mentioned above) that does the following:
- load the structure
- parse the structure to create an outline of a DocBook book
instance for the document
- use the outline to copy all the help nodes into a structure
to create a valid DocBook book
- run our standard book process to produce FO and then run it
through XEP to produce a PDF of the document
This is the same document, processed into two different formats for
different purposes. Having the assembly provide information on the type
of document makes it possible to do a better job of the production
process based on information provided by the document rather than
depending on different Ant files (we load portions of Ant build files
depending on the document type and version that are identified in the
build file). While this obviously moves into the area of talking to the
render system and thus dependencies on the render environment, it also
makes the description of the document more complete (this is a help
system, regardless of what output format I am rendering it into). The
assembly model will also give us better control over the resulting
outputs, since now there is no way to override the document model of the
book that is built into the transform environment.
I can generate a simple version of this (the ones we actually produce
have hundreds of help nodes, far more than an example can practically
uses) based on the sample of the assembly I worked on, if that would
help, or based on some other content model if that is more appropriate.
However, I think this description gets at the heart of what I think the
type attribute is for. Producing the document from an assembly and a
set of topics can be done pretty rapidly by using simple translations
from the new grammar to the existing grammar we use (we already have a
multi-stage production process that uses temporary files for
intermediate stages in the production process).
I hope this clarifies the purpose of the type attribute. I am never
sure about email exchanges, since the feedback loop is so long. Let me
know if anything is unclear or confusing and I will try to improve the
descriptions. I think this definitely needs to be dealt with in The
Definitive Guide, and will probably require some elaboration in Bob's
book.
Regards,
Larry
Original Message-----
From: Norman Walsh [mailto:ndw@nwalsh.com]
Sent: Tuesday, July 13, 2010 8:09 AM
To: docbook-tc@lists.oasis-open.org
Subject: Re: [docbook-tc] Assembly questions
"Gershon Joseph (gerjosep)"