From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=0.7 required=5.0 tests=BAYES_00,MSGID_RANDY autolearn=no autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 103376,e61c8636ef35379d X-Google-Attributes: gid103376,public X-Google-ArrivalTime: 2001-01-16 13:40:21 PST Path: supernews.google.com!sn-xit-02!supernews.com!news.gv.tsc.tdk.com!falcon.america.net!sunqbc.risq.qc.ca!newsfeed.mathworks.com!news.maxwell.syr.edu!nntp2.deja.com!nnrp1.deja.com!not-for-mail From: mark_lundquist@my-deja.com Newsgroups: comp.lang.ada Subject: RE: Examples in Docs Date: Tue, 16 Jan 2001 21:29:13 GMT Organization: Deja.com Message-ID: <942eet$das$1@nnrp1.deja.com> References: NNTP-Posting-Host: 130.213.202.184 X-Article-Creation-Date: Tue Jan 16 21:29:13 2001 GMT X-Http-User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows NT; DigExt) X-Http-Proxy: 1.1 x64.deja.com:80 (Squid/1.1.22) for client 130.213.202.184 X-MyDeja-Info: XMYDJUIDmark_lundquist Xref: supernews.google.com comp.lang.ada:4071 Date: 2001-01-16T21:29:13+00:00 List-Id: In article , comp.lang.ada@ada.eu.org wrote: > I believe that you have two subjects intertwined. Since the Ada Reference > Manual is an official document, for purposes of correctness and maintenance, > it should be kept as small as possible. However, when it serves as a > teaching document (using teaching in a broad sense), the user would benefit > from examples. Since many of us make use of the HTML version, it should be > possible to add hypertext linkages to jump to examples in this derived > document 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. A nice companion would be a HT version of the Rationale with HLs linking to the RM (and maybe from the RM). 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... same w/ Steelman for the historically/legally inclined :-) I'm now diluting my own idea with brain fartage so I will stop... -- -- Post (Brain.Fart); -- :-) mark lundquist Sent via Deja.com http://www.deja.com/