Re: [dita] Publishing <topichead>

[Eliot Kimber <ekimber@reallysi.com>]

The original design would have been clearer if there had been an "abstract"
base class from which topicref, topichead, topicgroup, and the rest were
then specialized.

The explanation challenge is that you can't just say "topicref", you have to
say "topicref with @href/@keyref" or "topicref with navigation title but no
@href/@keyref" or "topicref with neither navigation title nor @href/@keyref"
as well as "topicref with @href/@keyref and processing-role of "resource".

All of the configurations are "topicrefs" in the very generic sense, but all
of these possible configurations of resource binding and navigation title
are semantically distinct in the DITA architecture.

We can use the specializations that reflect each of these configurations
informally to mean topichead vs. keydef vs. topicref but in the spec we have
to say "topicref + {qualifications}" because the base type is topicref and
the use of the specializations is not mandatory.

It would clearer to say that maps consist of sets of "map items", which may
be resource-binding items (keydef), navigation-defining-items (topichead),
navigation-position-defining items (topicref), item groups (topicgroup).

Maybe in DITA 2.0.


On 1/25/11 5:54 AM, "Robert D Anderson" <robander@us.ibm.com> wrote:

> Hi Ian,
> 
> That is part of the design for topicref and topichead. There are several
> such convenience elements in DITA, which are defined in order to simplify
> authoring and make the intent clearer. In addition to topichead, there is
> topicgroup (which groups elements without allowing a title or href), or
> keydef (which requires the keys attribute). You can do the same thing with
> a topicref element, but these specializations simply make it more
> convenient. The Mapgroup overview page explains this, using topichead as an
> example:
> http://docs.oasis-open.org/dita/v1.2/os/spec/common/mapgroup-d.html
> 
> The specification topic on DITA navigation specifically addresses the TOC
> issue; it mandates that a TOC node be created for "every <topicref> element
> (or specialization thereof) that references a topic or specifies a
> navigation title", apart from the exceptions listed:
> http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/ditanav.html
> 
> Based on that topic - the topicref <topicref navtitle="Sample"/> will be
> included in the TOC. The topichead element is a specialization of topicref,
> so <topichead navtitle="Sample"/> will also appear in the TOC.
> 
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit
> 
> 
> 
> From:   ian balanza-davis <ibalanza_davis@yahoo.co.uk>
> To:     Robert D Anderson/Rochester/IBM@IBMUS
> Cc:     dita <dita@lists.oasis-open.org>
> Date:   01/25/2011 12:25 PM
> Subject:        Re: [dita] Publishing <topichead>
> 
> 
> 
> That may be possible, but is it desirable?
> 
> From the spec:
> "The <topichead> element provides a title-only entry in a navigation map,
> which should appear as a heading when the map is rendered as a table of
> contents. In print contexts it should also appear as a heading in the
> rendered content."
> 
> "The <topicref> element identifies a topic (such as a concept, task, or
> reference) or other resource."
> 
> If those are accurate statements, it would seem to me (and I am happy to be
> corrected) that <topicref navtitle="sample"/>, while supported, should be
> expressed as <topichead navtitle.../>
> 
> It would also seem imply that @href should be mandatory on a topicref.
> 
> Ian
> 
> From: Robert D Anderson <robander@us.ibm.com>
> To: Tarun Garg <tarung@adobe.com>
> Cc: dita <dita@lists.oasis-open.org>
> Sent: Tue, 25 January, 2011 10:19:06
> Subject: Re: [dita] Publishing <topichead>
> 
> Hi Tarun,
> 
> A topichead does imply a container heading, so for a TOC this results in a
> hierarchy change. The same is true of other topicref elements that specify
> a title, but do not reference a topic; that is, <topichead
> navtitle="Sample"/> with no other attributes is equivalent to <topicref
> navtitle="Sample"/> with no other attributes.
> 
> Using the Example in the specification [1]:
> <map>
>   <topichead>
>     <topicmeta><navtitle>Computers</navtitle></topicmeta>
>     <topicref href="eniac.dita"/>
>     <topicref href="system360.dita"/>
>     <topicref href="pdp8.dita"/>
>   </topichead>
>   <topichead navtitle="Books">
>     <topicref href="hardback.dita"/>
>     <topicref href="paperback.dita"/>
>   </topichead>
> </map>
> 
> This would typically be rendered in a TOC as something like:
> Computers
> ...ENIAC
> ...System/360
> ...PDP-8
> Books
> ...Hard back books
> ...Paperback books
> 
> [1] http://docs.oasis-open.org/dita/v1.2/os/spec/langref/topichead.html
> 
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit
> 
> Tarun Garg <tarung@adobe.com> wrote on 01/25/2011 10:05:33 AM:
> 
>> From: Tarun Garg <tarung@adobe.com>
>> To: dita <dita@lists.oasis-open.org>
>> Date: 01/25/2011 10:20 AM
>> Subject: [dita] Publishing <topichead>
>> 
>> I am asking something very basic and I am not sure if this has been
>> discussed earlier on this forum.
>> 
>> While publishing, does <topichead> element imply a hierarchy change
>> for the contained <topicref> elements ?
>> 
>> Regards,
>> Tarun Garg
>> 
> 
> 
> ---------------------------------------------------------------------
> 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
> 
> 
> 
> 
> ---------------------------------------------------------------------
> 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
> 

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com