RE: [dita] My AI, documentation of conref restrictions

["Gershon Joseph (gerjosep)" <gerjosep@cisco.com>]

Hi Bruce,

 

Thanks for pulling this together. Your rework looks good. I've attached my comments -- just minor editorial catches marked draft-comment/@author="gerjosep".

 

--

Gershon

 

---

From: Bruce Nevin (bnevin)
Sent: Tuesday, November 03, 2009 7:06 AM
To: dita@lists.oasis-open.org
Subject: [dita] My AI, documentation of conref restrictions

Su-Laine recognized that some of the restrictions that concerned her are due to XMetaL being in some respects more strict than the spec in its treatment of conref. Nevertheless, in surveying topics about conref, keys, etc., it became increasingly clear to me how the nexus of interrelated parts that constitutes DITA support for use by reference requires an overview in one place, with links to more detailed topics on the individual pieces.

 

With some discussion with Kris and with Eliot, my approach to this evolved into a rewrite of the "Content reuse" topic (conref.dita). Judging from draft comments in that topic, I am wading boldly in where angels fear, etc., but I see no effective alternative. However, I did not modify the original conref.dita, my rewrite is in a separate file. This is anomalously named Use_By_Reference.dita and can be renamed appropriately if the decision is made to use it.

 

Here are the main points of what I have done:

• Reorganized it as sections in one concept topic.
• Changed source/target to referencing/referenced.
• Added related-links for access to the more detailed topics.
• Changed the title to "Use by reference" rather than "Content inclusion".
• Included a brief section on <topicref>.
• Included, but on advice from Eliot commented out, discussion of use of <fn> by reference from <xref>.
• Recast some of the text for clarity.

This document needs technical review to make sure I haven't munged things, and obviously any of this can be changed, including the fundamental strategy.

 

There are two technical questions in the body of the topic, written in XML comments, where the language seemed to me unclear or incomplete and I couldn't resolve the intended meaning.

 

There is also a question about how to make one of the related links, which should probably be dealt with off line with Kris or someone. Here it is, and it is also noted in a comment written on the last of the related links. This is the link to "Common attribute definitions", which is currently rendered in the lang ref, but which probably should be rendered in the arch spec. (If I understood him correctly, Eliot thought nothing in the common folder should be used in the lang ref, but this is a clear counterexample.) I found  ../common/complexattributedefinitions.dita but don't yet know enough about the organization of the content to see how the content that is rendered below it in the lang ref gets assembled. Is a link pointing to that (short) topic sufficient?

 

Seeing no information on how to upload a file for interested members to access from the wiki, I am attaching it. My apology if that's an annoyance to anyone.

 

    /Bruce

Use_By_Reference-gerjosep.dita