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=-1.9 required=5.0 tests=BAYES_00 autolearn=ham
	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-21 03:35:25 PST
Path: 
 supernews.google.com!sn-xit-02!sn-xit-04!supernews.com!xfer13.netnews.com!netnews.com!opentransit.net!news.tele.dk!128.39.3.166!uninett.no!ntnu.no!randhol+abuse
From: randhol+abuse@pvv.org (Preben Randhol)
Newsgroups: comp.lang.ada
Subject: Re: Examples in Docs, was Re: Escape Sequences in Strings
Date: 21 Jan 2001 11:35:24 GMT
Organization: Norwegian university of science and technology
Message-ID: <slrn96lidc.ekk.randhol+abuse@kiuk0156.chembio.ntnu.no>
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>
 <uwvbq11yf.fsf@gsfc.nasa.gov>
NNTP-Posting-Host: kiuk0156.chembio.ntnu.no
X-Trace: kopp.stud.ntnu.no 980076924 23128 129.241.83.82 (21 Jan 2001 11:35:24
 GMT)
X-Complaints-To: usenet@itea.ntnu.no
NNTP-Posting-Date: 21 Jan 2001 11:35:24 GMT
User-Agent: slrn/0.9.6.3 (Linux)
Xref: supernews.google.com comp.lang.ada:4255
Date: 2001-01-21T11:35:24+00:00
List-Id: <comp.lang.ada>

On 20 Jan 2001 14:02:48 -0500, Stephen Leake wrote:
>In general, I agree. But there are times when an external document is
>better:
>
>1) The document presents an overview of the design of a large system,
>   so it uses diagrams, and it doesn't belong in any one source file.

Yes, but wouldn't that go into the spec documentation?

>2) The document presents an algorithm that is best described by
>   mathematical notation; flat ASCII is just not good enough for this.

Yes that is true, though one could use LaTeX markup for equations within
the source code comment and have the parser generate a external
document. One could use the MathML (http://www.w3.org/Math/) as well,
but last time I look at it looked like a real pain[*] to write the
markup.

[*] Example:

x + a/b

<mrow>
   <mi> x </mi>
   <mo> + </mo>
   <mrow>
      <mi> a </mi>
      <mo> / </mo>
      <mi> b </mi>
   </mrow>
</mrow>

-- 
Preben Randhol ---------------- http://www.pvv.org/~randhol/ --
iMy favorite editor is Emacs!<ESC>bcwVim<ESC>
                                         -- vim best-editor.txt