Re: Examples in Docs

["Randy Brukardt" <randy@rrsoftware.com>]

mark_lundquist@my-deja.com wrote in message
<942eet$das$1@nnrp1.deja.com>...

>I've been thinking about how more thorough self-reference could make a
>HT version of the RM a really powerful tool, even without additional
>material such as examples (not to discount your idea, which I think is
>a good one).
>
>What I would like to have:
>
>1) every cross-reference anchor a hyperlink to the referenced text
>2) every use of a defined term (e.g. "protected action", "nominal
>subtype", "master", etc.) anchor a HL to the definition of the term
>3) the instance of every term in its definition anchor a HL to the
>index entry for the term
>4) HLs in the syntax summary/cross-reference
>
>My RM of choice :-) is the annotated version w/ Technical Corrigenda on
>the ACAA web site; the annotations help me understand why things are
>what they are, and I feel like I'm getting the "full meal deal".  A HT
>version of that that allowed the user to expand/elide the annotations
>would be great.


Humm, the HTML version of the RM on the ACAA website in fact includes
items 1 and 3 on your list above. (Try clicking on any index entry, and
you will be taken directly to the item referenced.)

Item  2 would be wonderful, but it would be very expensive to do (as the
source of the RM does not mark uses of terms in any special way).
Usefully picking them out with any automated method is bound to be very
incomplete.

Item 4 is partially accomplished by the HTML RM -- the section numbers
are hot links (so you can get to the section where the production is
defined). But not the individual items.

Therefore, I conclude that what you want is already available in the
HTML ARM available on the ACAA web site. When I building these versions
of the RM, I expected that almost all on-line use of the RM would use
these HTML versions (the PDF versions being restricted to printing).

>Throwing the AIs into the mix would create a document system that might
>be really nice for a small handful of people, but I don't know if it'd
>be worth the effort for that.

Well, almost all of the AIs included in the Technical Corrigendum (and
in the Record of Responses document, as well) are represented by (new)
annotations in the annotated version of the RM. The handful that don't
have annotations were too complex to explain in the limited time I had,
or simply didn't have an obvious point in the RM to put them. All such
annotations (and text changes as well) are linked to the associated
Defect Reports (the ISO term for AIs).

Of course, new AIs aren't included that way, but there are very few of
them finished at the moment, so you're not missing much...

I put a lot of thought into what could be accomplished with the time I
had available, and I'm glad that people appreciate that work (even if
they don't know yet that it was done for them!).

                    Randy Brukardt
                    ARG Editor