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

[Scott Hudson <scott.hudson@flatironssolutions.com>]

Originally, we had proposed something like:
Another option is to mirror the structure of definition lists, such 
that: <*relationships*> <*relationship* id="blog.docbook"> <arc 
id="*DocBook*">*DocBook*</arc> <instance linkend="blog.entry.5"/> 
<instance linkend="blog.entry.3"/> </*relationship*> </*relationships*> 
In this case, the term *DocBook*, is associated with 2 content 
resources. Any number of *relationships* can be defined with this method.

In this case, the <association> is the term/topic we are trying to relate:

<relationship type="seealso">
   <association>component</association>
   <instance linkend="ref.book"/>
   <instance linkend="ref.part"/>
   <instance linkend="ref.preface"/>
   <!-- ... -->
   <instance linkend="ref.index"/>
</relationship>


In this instance, the seealso is how this relationship could trigger 
specific rendering. The association of "component" is how they are 
related. Interesting that you bring up <title> perhaps that should be 
allowed in <relationship> for labeling purposes. The association should 
specifically be a term or URI (if you were trying to map this to a 
specific topic in a known topic map).

Hopefully this is more clear?

--Scott

On 11-Dec-09 4:36 PM, Norman Walsh wrote:
> 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
>
>