RE: [dita] references to ditabases without an explicit topicid

[Robert D Anderson <robander@us.ibm.com>]

As nobody else seems inclined to respond...

My personal expectation would be that if I reference a file in the map, I
expect that the whole file will show up in the XHTML / PDF / etc unless I
say otherwise. I think it would be a shock to reference a DITA combination
file, and find only the first topic in my output.

Anybody else want to voice an expectation?

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit
(507) 253-8787, T/L 553-8787

"Grosso, Paul" <pgrosso@ptc.com> wrote on 07/13/2006 05:12:54 PM:

> Robert,
>
> Thanks for the response.  Unfortunately, I'm not sure
> it gives me a complete answer to my question.
>
> What should a topicref with an href to a file with no
> specific topicID specified do when the file is a ditabase
> document that contains more than one unnested topic?
>
> Your answer makes it clear what should happen as far as
> linking goes.  But I'm still unclear on what should happen
> about including the topics in, say, a PDF.
>
> paul
>
> > -----Original Message-----
> > From: Robert D Anderson [mailto:robander@us.ibm.com]
> > Sent: Thursday, 2006 July 13 14:58
> > To: dita@lists.oasis-open.org
> > Subject: Re: [dita] references to ditabases without an
> > explicit topicid
> >
> > Hi Paul - maybe somebody else can give a more authoritative
> > answer, but from my experience...
> >
> > The toolkit does not break files up when creating XHTML. So, if you
> > reference "file.dita", or "file.dita#first-topic", or
> > "file.dita#last-topic", the full file will generate XHTML.
> > Once the spec
> > fully explains how to use the chunk attribute, I expect that
> > the toolkit
> > will add support for that attribute as a way to break apart
> > topics when
> > generating XHTML.
> >
> > The main impact of that "file name equals first topic"
> > assumption, at least
> > today, comes about when linking. If you reference
> > "file.dita", then any
> > generated links are added after the body of the first topic.
> > If there are
> > sub-topics, they appear below those links. Any generated
> > links to this file
> > will pull the title from the first topic in the file. This is
> > true whether
> > it's a <dita> mixed file, or of a single topic type. So, this
> > demonstrates
> > the behavior that links to/from "file.dita" are treated as
> > links to/from
> > the first topic.
> >
> > If you give a topic ID in your reference, then links will be
> > placed after
> > the body of that topic, regardless of what type of file it is
> > or what else
> > is included. Generated links to this file will get the title from the
> > specific topic.
> >
> > In terms of conref - my understanding is that conref="file.dita" is
> > supposed to go to the first topic in the file. In a <dita>
> > mixed file, this
> > means the first child of <dita>. In a single-type file, this
> > will bring in
> > that main topic and anything nested inside it. This
> > clarification was made
> > after we wrote the conref code, and I haven't thought about
> > it in a long
> > time, so I can't say for sure if the toolkit code was updated
> > to work this
> > way. If not, we should open a bug report on it.
> >
> > Does that help?
> >
> > Robert D Anderson
> > IBM Authoring Tools Development
> > Chief Architect, DITA Open Toolkit
> > (507) 253-8787, T/L 553-8787
> >
> > "Grosso, Paul" <pgrosso@ptc.com> wrote on 07/12/2006 02:29:41 PM:
> >
> > > Our developers are trying to understand what it means
> > > to have a reference to a ditabase from a topicref in
> > > a map where the href value does not include a fragment
> > > identifier (e.g., "path" rather than "path#topicid").
> > > Specifically, is just the first topic picked up or
> > > all the topics?
> > >
> > > The DITA 1.0 Architectural Spec doesn't seem to
> > > address this.
> > >
> > > In the DITA 1.0 Language Specification, there are
> > > a few references that seem to address this issue:
> > >
> > > In the Language Spec. in the descriptions for the
> > > conref attribute on topic, concept, reference, and
> > > task elements it says in part:
> > >
> > >  During output processing, a lookup process will pull the
> > >  contents of the first topic into the calling topic markup
> > >  that has the conref attribute.
> > >
> > > And a bit later in the same description it says:
> > >
> > >     Target elsewhere in the same file:
> > >         conref="#topicid"
> > >
> > >     First topic in a different file:
> > >         conref="filename.xml"
> > >
> > >     Specific topic in different file:
> > >         conref="filename.xml#topicid"
> > >
> > > And in the href description for the link element in a
> > > topic, it says:
> > >
> > >    Target elsewhere in the same file:
> > >         conref="#topicid"
> > >
> > >     First topic in a different file:
> > >         conref="filename.dita"
> > >
> > >     Specific topic in different file:
> > >         conref="filename.dita#topicid"
> > >
> > > There is nothing specific about this one way or another in the
> > > other href descriptions for the elements topicref and xref.
> > >
> > > Using the DITA Open Toolkit, for html output, only one link
> > > appears in the index.html file, but all of the topics from
> > > the ditabase were included in the other .html file.
> > >
> > > Can someone confirm what is the expectation when one encounters
> > > an href to a ditabase without a fragment identifier on a topicref.
> > > Should just the first topic from the ditabase be included or
> > > should all of the topics from the ditabase be included?
> > >
> > > paul
> >