RE: [dita] Publishing <topichead>

[Tarun Garg <tarung@adobe.com>]

Hi Robert,

Does that mean that it will also lead to change in numbering in the TOC ? 

I mean (taking again your example with some change),

<map>
  <topicref href="systems.dita"/>
  <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>

Will get rendered in a TOC as something like:
1. Systems
2. Computers
	2.1 ENIAC
	2.2 System/360
	2.3 PDP-8
3. Books
	3.1 Hard back books
	3.2 Paperback books


Also, the spec mentions that - "In print contexts it should also appear as a heading in the
rendered content."
Will the similar hierarchy & numbering change apply there as well ?

Regards,
Tarun Garg


-----Original Message-----
From: Robert D Anderson [mailto:robander@us.ibm.com] 
Sent: Tuesday, January 25, 2011 5:25 PM
To: ian balanza-davis
Cc: dita
Subject: Re: [dita] Publishing <topichead>

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