RE: [dita] What are the implications of <navref> for key space construct

Actually navref was part of DITA 1.0

navref

The <navref> element references a map file from within a map file. The reference is resolved at runtime

for Eclipse navigation, typically to pull together the navigation for multiple components into a product

navigation. This element is for runtime resolution of references, and is for navigation only. It is currently

only supported by Eclipse output.

For build-time integration, you can use the conref attribute on an element inside the map (for example, a

topicref) to pull in content from a matching element (for example, another topicref) in another map.

The DITA 1.1 description is a bit longer:

navref

The <navref> represents a pointer to another map which should be preserved as a transcluding link

rather than resolved. Output formats that support such linking will integrate the target when displaying

the referencing map to an end user.

For example, if a map is converted to the Eclipse help system format, the DITA element <navref

mapref="other.ditamap"/> should be converted to the Eclipse element <link toc="other.xml"/>. When

Eclipse loads the referencing map, it will replace this link element with the contents of other.xml,

provided that other.xml is available.

Note that not all output formats will support such linking. In order to include target maps directly

without depending on the output format, you may reference the map with a topicref while setting the

format attribute to ″ditamap″. For example, the following markup represents a literal inclusion of the

map ″other.ditamap″ (similar to a conref):

The current wording in the DITA 1.2 draft looks identical to the DITA 1.1 wording.

We could take something from the DITA 1.0 description to heart, “[navref] is for navigation only”, and simply state that “the use of key definitions in maps referenced using <navref> is currently undefined and the processing of key definitions, if any, may vary from implementation to implementation”. Or perhaps the use of key definitions in maps referenced using <navref> is not supported and implementations may, but are not required to, issue a warning message when key definitions are present”.

-Jeff

> -----Original Message-----

> From: Eliot Kimber [mailto:ekimber@reallysi.com]

> Sent: Sunday, December 06, 2009 10:27 PM

> To: Ogden, Jeff; Robert D Anderson

> Cc: dita

> Subject: Re: [dita] What are the implications of <navref> for key space

> construction?

> Navref was in DITA 1.1--I had no idea. Obviously we can't replace it

> with a

> value of processing-role in that case. I must have always assumed it

> was a

> specialization of topicref.

> My questions about the implications for key resolution still stand, but

> I'll

> have to think about what I think the right answer should be in light of

> Robert's explanation. I'm not sure I agree with his assertion that the

> current language spec text implies anything but I'm also not sure what

> would

> be sensible.

> Cheers,

> E.

> On 12/6/09 8:21 PM, "Ogden, Jeff" <jogden@ptc.com> wrote:

> > At PTC we don't have any explicit support for navref, so I am a

> novice

> > about its use and haven't thought about it much.

> >

> > But having said that, my thoughts are similar to Robert's -- that

> > processing of maps referenced by navref is deferred and so any key

> > definitions would be deferred as well either because the map isn't

> > available or processing key definitions earlier isn't the right thing

> to

> > do.

> >

> > I guess one could make an argument that processing of key definitions

> > and key resolution should be deferred in this case, but that seems

> like

> > it would require a big discussion and has huge implications for

> > processing and so probably isn't something we can consider for DITA

> 1.2.

> >

> > Likewise, Eliot's thoughts of changes to make navref a specialization

> of

> > topicref using @processing-role just doesn't seem like something that

> > can be considered for DITA 1.2 or likely at all until DITA 2.0.

> >

> > -Jeff

> >

> >> -----Original Message-----

> >> From: Robert D Anderson [mailto:robander@us.ibm.com]

> >> Sent: Sunday, December 06, 2009 11:41 AM

> >> To: Eliot Kimber

> >> Cc: dita

> >> Subject: Re: [dita] What are the implications of <navref> for key

> > space

> >> construction?

> >>

> >> As you say, navref is essentially a form of deferred navigation. As

> >> such

> >> though - it is most common in my experience for this to be used when

> >> the

> >> target map is not available to the author working with the current

> > map.

> >> That's actually the reason (as I understand it) for deferring the

> >> navigation. In particular, authors building for Eclipse use this to

> >> reference another component that may or may not be available. When

> the

> >> other component is installed, the navref results in a TOC that pulls

> > in

> >> the

> >> other component's TOC entries. When it is not available, nothing is

> >> pulled

> >> in.

> >>

> >> So, I'm less certain that navrefs should be treated the same as maps

> >> referenced via topicref - primarily because I have never treated

> them

> >> that

> >> way in the past. The 1.1 specification also makes a distinction

> > between

> >> the

> >> two ways of referencing a map. It says that:

> >> "The <navref> represents a pointer to another map which should be

> >> preserved

> >> as a transcluding link rather than resolved. Output formats that

> >> support

> >> such linking will integrate the target when displaying the

> referencing

> >> map

> >> to an end user."

> >>

> >> To me, this means that no attempt is made to retrieve the other map

> >> until

> >> the content is displayed to a reader, so I would not expect it to be

> >> used

> >> to set key values.

> >>

> >> Any other thoughts?

> >>

> >> Robert D Anderson

> >> IBM Authoring Tools Development

> >> Chief Architect, DITA Open Toolkit

> >>

> >> Eliot Kimber <ekimber@reallysi.com> wrote on 12/05/2009 01:21:43 PM:

> >>

> >>> Eliot Kimber <ekimber@reallysi.com>

> >>> 12/05/2009 01:21 PM

> >>>

> >>> To

> >>>

> >>> dita <dita@lists.oasis-open.org>

> >>>

> >>> cc

> >>>

> >>> Subject

> >>>

> >>> [dita] What are the implications of <navref> for key space

> >> construction?

> >>>

> >>> Somehow I had never noticed <navref> before.

> >>>

> >>> Navref is not a specialization of topicref, it is a new element

> type

> >> that

> >>> creates a map-to-map dependency where the integration of the

> >> referenced

> >> map

> >>> into the effective navigation tree is deferred (essentially a form

> > of

> >>> deferred conref).

> >>>

> >>> The current reference entry for navref doesn't say anything about

> > how

> >>> navref-referenced maps contribute to the effective compound map

> they

> >> are

> >>> used in, in particular, how they contribute to the key space and

> how

> >> they

> >>> contribute relationship tables.

> >>>

> >>> I think the only right answer is that navref-included maps are

> >> treated

> >> just

> >>> like maps referenced via topicref but I want to make sure this is

> > the

> >> intent

> >>> of the Architects before I write words to that effect in the spec.

> >>>

> >>> Looking at it now, navref seems unnecessary now that we have

> >>> @processing-role, in that the same effect could be achieved by

> > adding

> >> a

> >>> value such as "deferred-navigation" to @processing-role (remember

> >> that we

> >>> invented processing-role after inventing <navref>).

> >>>

> >>> As far as I can tell from the description of navref, causing

> >> navigation

> >>> integration to be deferred is the only thing navref does so a

> >>> processing-role value should be as good a signal as <navref> to a

> >> processor

> >>> that cares.

> >>>

> >>> As it is, everywhere we talk about topic-ref referenced maps in the

> >> context

> >>> of any map-related processing involving the effective map tree, we

> >> now

> >> have

> >>> to also mention <navref>. Given that, replacing <navref> with a new

> >>> @processing-role value seems like the less-disruptive change to the

> >> spec.

> >>>

> >>> Cheers,

> >>>

> >>> Eliot

> >>>

> >>> --

> >>> Eliot Kimber

> >>> Senior Solutions Architect

> >>> "Bringing Strategy, Content, and Technology Together"

> >>> Main: 610.631.6770

> >>> www.reallysi.com

> >>> www.rsuitecms.com

> >>>

> > ---------------------------------------------------------------------

> >>> 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: 610.631.6770

> www.reallysi.com

> www.rsuitecms.com

dita message