Re: [docbook-tc] A first stab at documenting assemblies

[Norman Walsh <ndw@nwalsh.com>]

Scott Hudson <scott.hudson@flatironssolutions.com> writes:
> For a more concrete example: Lets say you are building TDG. For the
> reference pages assembly, you could relate all of the component pages
> (book, part, preface, chatper, appendix, glossary, bibliography,
> article) with a "component" relationship.

Ok, let's play this out a bit. My assembly says something like this:

<relationship type="component">
  <association>DocBook Components</association> <!-- why not title? -->
  <instance linkend="ref.book"/>
  <instance linkend="ref.part"/>
  <instance linkend="ref.preface"/>
  <!-- ... -->
  <instance linkend="ref.index"/>
</relationship>

That's all well and good. Now how does the processing system know what
to do with "component" type relationships? What does it render on the
reference pages. Do we imagine that there's going to be enough
sophistication to generate what the pages currently contain:

<refsect1>
<title>See Also</title>

<para><xref linkend="db.element.part"/>,
<xref linkend="db.element.part"/>, ... </para>
<refsect1>

> You could have another for section types, another for meta, etc.
>
> It's a way of applying a taxonomy to content instances, if you will.
> The See Also section in TDG, for example, could be generated from the
> relationships and easily updated from one file, rather than maintained
> at each content chunk.
>
> I was just hoping we could demonstrate a simple example of it.

And I'll be happy to demonstate it as soon as I understand it :-)

Other questions:

1. Why "association", why not "title"?
2. Relationships are currently defined as between modules, but inline
   relatedlinks are between resources (I assume). Isn't that going
   to be problematic?

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | How can there be laughter, how can
http://www.oasis-open.org/docbook/ | there be pleasure, when the world
Chair, DocBook Technical Committee | is burning?--The Dhammapada
                                   | (probably 3rd century BC)

PGP signature