OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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
  - 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
  - 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.


-----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:


in DocBook SVN.

                                        Be seeing you,

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 |

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]