dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: My AI, documentation of conref restrictions
- From: "Bruce Nevin (bnevin)" <bnevin@cisco.com>
- To: <dita@lists.oasis-open.org>
- Date: Mon, 2 Nov 2009 23:06:08 -0600
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.dita
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]