RE: [docbook-tc] Assembly questions

["Gershon Joseph (gerjosep)" <gerjosep@cisco.com>]

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)" <gerjosep@cisco.com> writes:

> For what it's worth, I have seen many use cases in DITA where the same

> bookmap or map is used to represent different types of deliverables as

> well as different formats of those deliverables. So I side with Larry,

> and if you're leaving it as-is I'm happy. This particular use case can

> be challenging in DITA too, and I feel the additional functionality we

> have in DocBook is much more elegant.

Ok. I'm happy to be persuaded that there's more going on here than my
limited imagination can grasp, but if that's the case, I need some help
understanding how all these pieces interact.

Can someone construct a concrete example that utilizes this additional
functionality, describing both the input and the different outputs and
how the processor uses the information in the assembly file to generate
them?

I've started building an assembly example in the TDG5. It's a set of
topics about installing and using a printer. The tools that I'm
developing aren't anywhere public yet, but the topic sources and the
assembly file are here:

  /docbook/defguide5/en/examples/printer

in DocBook SVN.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Every new beginning comes from
http://www.oasis-open.org/docbook/ | some other beginning's end.
Chair, DocBook Technical Committee |

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php