dita — archive

proposal for DITA 1.3: same document/same topic DITA reference syntax

From: Jeff Ogden <[email protected]>
To: [email protected]
Date: Wed, 10 Sep 2008 03:42:00 -0000













Comments edited into the text below.

 

   -Jeff

 











From: Bruce Nevin
(bnevin) [mailto:[email protected]]

Sent: Tuesday, September 09, 2008
11:07 PM

To: Ogden, Jeff;
[email protected]

Subject: RE: [dita] proposal for
DITA 1.3: same document/same topic DITA reference syntax



 

In the
existing syntax, null filename signifies same document, so in this proposal .
following null filename signifies same topic. A nice symmetry:

  

#. 

   
same document, same topic 

#./elementid


   
same document, same topic, specified element within it

#topicid

    same
document, specified topic within it

#topicid/elementid

   
same document, specified topic within it, specified element within that

filename.dita#topicid

   
specified document, specified topic in it 

filename.dita#topicid/elementid

   
specified document, specified topic in it, specified element within that

 

An
element referring to itself is not supported, and I suppose it's assumed not to
occur. If there were a use case, #./. would be the appropriate syntax. Do you
want to support it just in case?

 

I couldn’t think of a legitimate use
case and so didn’t want to clutter things up with something that wouldn’t
be used and which might in fact be confusing or dangerous. If there is a case
where a same element reference would be useful, we could consider adding this
form.

 

What
happens if the topicid value is the id of the containing topic? 

 

I don’t understand the question. 
The id represented by the dot will always be the id of the containing topic.

 

#topicid
== #. redundantly, or made illegal?

#topicid/elementid
== #./elementid redundantly, or made illegal?

 

All four of these forms would be legal. Authors
would be free to use the syntax that best meets their needs.

 

This is
shorthand for potential existing syntax. That is, if filename.dita is the name
of the containing file, then

  

filename.dita#topicid
== #topicid or #. redundantly

filename.dita#topicid/elementid
== #topicid/elementid or #/elementid redundantly

 

Is the line above missing a dot? Should it
read:

filename.dita#topicid/elementid
== #topicid/elementid or #./elementid
redundantly

 

How is
that handled now? And with this proposal, do we make it illegal, or accept
it as a redundant alternative?

 

I don’t see any reason for any of
these forms to be illegal.  They all reference the same element and could
be used interchangeably as authors see fit.

 

   
/Bruce

 



 







From: Ogden,
Jeff [mailto:[email protected]]

Sent: Tuesday, September 09, 2008
10:02 PM

To: [email protected]

Subject: [dita] proposal for DITA
1.3: same document/same topic DITA reference syntax

Here is a proposal for DITA 1.3 or whatever comes after DITA
1.2. Not sure if this would be proposed feature #13001 or not.

 

Paul Grosso and I would like the DITA TC to consider
defining a syntax for same document/same topic references in DITA 1.3.

 

The DITA Specification currently defines a syntax that
provides for same document references in topics and maps:

 

      #mapelementid

      #topicid

      #topicid/elementid

 

A suggested syntax for same document/same topic references
is:

 

      #.
            (pound-sign
dot forward-slash)

#./elementid   (pound-sign dot forward-slash elementid)

 

Where . (dot)
represents the id of the current topic.

 

This syntax is only used for same document topic references.
It is an error to use this syntax when a path or filename is given or for a
same document map reference.

 

The uses for a same document/same topic reference syntax are
similar to the uses for the existing same document reference syntax. The syntax
allows sections of DITA markup that include URI references to be written in a
self-contained location independent fashion. The markup could be moved from or
included from one topic document to another using copy and past, content
references, xincludes, entities, or other means without the need to adjust the
URI reference to include the id of the topic at the target location.