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-20 07:11:57 PST
Path: 
 supernews.google.com!sn-xit-02!supernews.com!nntp-relay.ihug.net!ihug.co.nz!news-spur1.maxwell.syr.edu!news.maxwell.syr.edu!nntp2.deja.com!nnrp1.deja.com!not-for-mail
From: Robert Dewar <robert_dewar@my-deja.com>
Newsgroups: comp.lang.ada
Subject: Re: Examples in Docs, was Re: Escape Sequences in Strings
Date: Sat, 20 Jan 2001 15:00:46 GMT
Organization: Deja.com
Message-ID: <94c96r$jiv$1@nnrp1.deja.com>
References: <93objj$guk$1@nnrp1.deja.com>
 <ZSS76.120778$A06.3893142@news1.frmt1.sfba.home.com>
 <93q77h$rr6$1@nnrp1.deja.com> <940f9j$nj2$1@nnrp1.deja.com>
 <94299p$8dd$1@nnrp1.deja.com>
 <J_e96.5326$DI.58950@e420r-atl1.usenetserver.com>
 <94a2jj$tc2$1@nnrp1.deja.com> <94c73f$hs9$1@nnrp1.deja.com>
 <slrn96j8l9.ig.randhol+abuse@kiuk0156.chembio.ntnu.no>
NNTP-Posting-Host: 205.232.38.14
X-Article-Creation-Date: Sat Jan 20 15:00:46 2001 GMT
X-Http-User-Agent: Mozilla/4.61 [en] (OS/2; U)
X-Http-Proxy: 1.0 x53.deja.com:80 (Squid/1.1.22) for client 205.232.38.14
X-MyDeja-Info: XMYDJUIDrobert_dewar
Xref: supernews.google.com comp.lang.ada:4235
Date: 2001-01-20T15:00:46+00:00
List-Id: <comp.lang.ada>

In article
<slrn96j8l9.ig.randhol+abuse@kiuk0156.chembio.ntnu.no>,
  randhol+abuse@pvv.org (Preben Randhol) wrote:

> I agree. If one wanted an external documentation, one can run
> a script/program which extracts the documentation from the
> sourcefiles and assemble it as one likes. Then it would be
> easier to maintain an external document as well if that was
> desired.

Yes, that seems like a good compromise but in this case I
favor minimal markup, so that the documentation can still
be easily read with ordinary editing tools while working
with the source. One can imagine a universal environment
allowing fancy markup, and that would be fine, if and
when it is universal :-)

An interesting example of this approach in action (extracting
documentation from listings) would be to generate a manual for
the GNAT component library (GNAT.xxx) where all the user level
documentation is currently maintained in the specs of the
packages.


Sent via Deja.com
http://www.deja.com/