Hi Norm, et al,
I think this has been very helpful, and shows the potential assemblies
in increasing orders of complexity in a user-friendly manner. I think
there is a typo in the 2nd para of 5. Example Assembling an Online Book.
"but it will be in the long run" should be "but it will be better in the
long run".
I'd like to include an example of adding the relationships to your last
example. Perhaps something like this:
Best regards,
--Scott
Scott Hudson
Senior XML Architect
+1 (303) 542-2146 | Office
+1 (720) 663-SCOT [7268] | Gvoice
Scott.Hudson@flatironssolutions.com
http://www.flatironssolutions.com
Norman Walsh wrote:
> Hi folks,
>
> I'm offline for a bit, distracting myself from other things by trying
> to tie up some loose ends. Attached, find my first attempt to document
> the assembly proposal.
>
> I did this partly to see if I understood it. No doubt, there are
> places where I *miss*understood it; there are certainly a few places
> where I changed it to suite what I think are the requirements.
> Consequently, I've documented what amounts to a slightly different
> proposal.
>
> I'd be interested, in particular, to know what capabilities of the
> original proposal cannot be addressed with this one.
>
> The description has two parts, an attempt at high-level exposition and
> a few narrative examples. The examples are probably better than the
> high-level exposition.
>
>
>
> ------------------------------------------------------------------------
>
> OASIS logo
>
>
> DocBook Assemblies Version
>
>
> Specification URIs:
>
> This Version:
> http://docs.oasis-open.org/docbook/specs/--spec--.html <--spec--.html>
> http://docs.oasis-open.org/docbook/specs/--spec--.pdf <--spec--.pdf>
> http://docs.oasis-open.org/docbook/specs/--spec--.xml <--spec--.xml>
>
> Technical Committee:
> Chair
> Editor
>
>
> Abstract:
>
>
> Status:
>
>
> Notices:
>
> *Table of Contents*
>
> 1. Physical structure <#physical>
> 2. Logical structure <#logical>
> 3. Assembly Files <#R.1.15>
>
> 3.1. Resources <#resources>
> 3.2. Structures <#structures>
> 3.3. Relationships <#relationships>
> 3.4. Transformations <#transformations>
>
> 4. Example: Assembling a Printed Book <#ex-book>
> 5. Example: Assembling an Online Book <#ex-html>
> 6. Example: Assembling an Online Reference <#ex-ref>
>
> One modern school of thought on technical documentation stresses the
> development of independent units of documentation, often called
> topics, rather than a single narrative. Instead of writing something
> that DocBook users would easily recognize as a book consisting of a
> preface, several consecutive chapters, and a few appendixes, the
> author (or authors) write a set of discrete topics covering aspects of
> the system as if they were wholly independent.
>
> In a typical online presentation system, for example the world wide
> web or online help, each topic is a page that stands alone. Except, of
> course, that just as no man is an island, no topic is completely
> unrelated to the other topics that are available.
>
> From any given topic, there may be topics of obviously related
> interest. The nature of the relationships may vary. Some topics are
> related by physical proximity (if you're interested in the ink
> cartridges in a printer, you may also be interested in the print
> head), others by their procedural nature (adding or replacing memory,
> adding or replacing a hard drive, or even changing the CPU are all
> topics that might logically follow a topic that describes how to open
> the computer case).
>
> In a single narrative, it is the responsibility of the author to
> manage these relationships. He or she can reasonably assume that
> anyone reading chapter 4 has read chapters 1, 2, and 3. If the reader
> needs to be directed elsewhere, a cross reference can be used (for
> example, “for more information on paper jams, see Section 3.5, /The
> Paper Path/”).
>
> In a topic-oriented system, authors are explicitly instructed to write
> independent units. No linear order can be assumed and many forms of
> explicit cross-reference are discouraged.
>
> Documentation managers treat the library of available topics very much
> as programmers treat libraries of available functions. Just as any
> given program can pick and choose from the available libraries, the
> documentation for any given system can pick and choose from the
> available topics.
>
> If you imagine a large documentation group managing the documentation
> for several related systems (different models of printer, different
> configurations of a software system, automobile engines assembled from
> different components, etc.) it's easy to see the appeal of
> topic-oriented authoring.
>
> In a successful deployment, you might find a library of say 1,000
> topics which, taken together, document five or six related systems,
> each of which uses 700-800 topics. Some topics are used in every
> system, many are used in several systems, and a small number of topics
> are unique to a specific system.
>
> In order to make such a documentation platform functional, you need
> not only the individual topics, but also some sort of “map” or
> “assembly” file that describes which topics from the library are used,
> what relationships exist between them and, at least for print
> presentation, what linear order should be imposed upon them.
>
> DocBook uses an assembly for this purpose.
>
> Editorial Notes
>
> I've taken some liberties with the assembly proposal. Mostly this was
> to make it simpler where I thought I could, without sacrificing
> expressive power. I could be wrong about the latter part.
>
> *
>
> Resources can directly contain arbitrary DocBook content, not
> just strings.
>
> *
>
> Structures can not contain arbitrary DocBook content, only info
> elements. Everything else can be included by reference to a
> resource. The indirection may be a bit inconvenient, but I think
> it simplifies structure quite a bit.
>
> *
>
> I removed type on structure because I couldn't figure it out.
>
> *
>
> I've moved renderas exclusively to output.
>
> *
>
> I harmonized chunking, output filenames, rendering, and
> transformation to output. Maybe output isn't the best name for
> this element.
>
> *
>
> I made some explicit choices about processing expectations that
> may not be exactly the same as we've previously discussed.
>
>
> 1. Physical structure
>
> The notion of a DocBook assembly is predicated on a few assumptions
> about the physical layout of the topics that are to be combined
> together into units of documentation. We call the units of
> documentation “structures” and the topics from which they are composed
> “resources”.
>
> For the most part, we assume that resources exist as stand alone
> documents accessible via URIs. The structures that result from
> assembling the resources together may be a single file (as in a single
> PDF book) or a collection of files (as in a web site or help system).
>
> Other arrangements are possible, but for simplicity in this document
> we assume that the resources are accessible via URIs and the resulting
> structures can be written to the local filesystem as one or more files.
>
>
> 2. Logical structure
>
> Many features of an assembly allow the assembly to update metadata
> associated with a document, for example changing the title or removing
> the metadata altogether.
>
> Throughout the description of assemblies, we assume that all metadata
> always occurs inside an info wrapper. In other words, although the
> following is perfectly legal:
>
>
>
>
> we always assume that this is instead represented with a single info
> element:
>
>
>
>
> Even in cases where there is no info element:
>
>
>
>
> we assume one is present:
>
>
>
>
> Authors /are not/ required to author in this way in order to use
> assemblies. Processing systems are to behave /as if/ they had.
>
> The assumption that all metadata is always present in a single,
> explicit info wrapper /greatly/ simplifies the exposition of
> assemblies without introducing any actual limitations.
>
>
> 3. Assembly Files
>
> An assembly has four major parts:
>
> resources
>
> Identifies a collection of topics. An assembly may identifer one
> or more collections.
>
> structure
>
> Identifies a single document. A document in this case is the
> particular collection of topics that forms the documentation for a
> product or system. An assembly may identify one or more structures.
>
> relationships
>
> Identifies relationships between resources. These relationships
> may be manifested in any number of structures during assembly. An
> assembly may identify any number of relationships.
>
> transformations
>
> Identifies transformations that can be applied during assembly. An
> assembly may identify any number of transformations.
>
>
> 3.1. Resources
>
> Individual resources are identified through a resource element:
>
>