Increasing the readability of Ada was RE: Examples in Docs

["Robert C. Leif, Ph.D." <rleif@rleif.com>]

From: Bob Leif
To: Robert Dewar et al.

I totally agree. However, if the inclusion of information into the Ada
source is to be maximized, then the XML annotation data type or equivalent
(structured comments) should be created for Ada or present documentation
technology should be applied to Ada source. If an XML schema were created
for Ada, an XML editor with a plug-in could be used to edit Ada source. This
would have several advantages: 1) future commercial editors could be readily
adapted for Ada. 2) The style information would be separated from the text.
A style sheet or separate schema could be employed for capitalization etc.
3) Special annotations could be created with the requirement that text be
entered or even specific elements must be entered. 4) Hyperlinks to external
documentation could be included. And 5) Mathematics could be rendered in
MathML, which provides the interesting possibility of translation of MathML
into Ada.

XML Schema Part 1: Structures
W3C Candidate Recommendation 24 October 2000
This version:
http://www.w3.org/TR/2000/CR-xmlschema-1-20001024/
(in XML (with its own DTD, XSL stylesheet (Nov REC version)) and HTML), with
separate provision of the schema and DTD for schemas described herein.
4.3.10 XML Representation of Annotation Schema Components

Mathematical Markup Language (MathML) Version 2.0
W3C Proposed Recommendation 08 January 2001
This version:
http://www.w3.org/TR/2001/PR-MathML2-20010108
Also available as: HTML zip archive, XHTML zip archive, XML zip archive, PDF
(screen), PDF (paper)
`

-----Original Message-----
From: comp.lang.ada-admin@ada.eu.org
[mailto:comp.lang.ada-admin@ada.eu.org]On Behalf Of Robert Dewar
Sent: Saturday, January 20, 2001 6:25 AM
To: comp.lang.ada@ada.eu.org
Subject: Re: Examples in Docs, was Re: Escape Sequences in Strings


In article <94a2jj$tc2$1@nnrp1.deja.com>,
  mark_lundquist@my-deja.com wrote:
> I think the idea of embedded hyperlinks in comments to
> navigate out to supporting documentation of the kind you
> mention could really be
> worthwhile (DING!  Cue for Bob-Leif-XML-followup :-) :-) :-)

Generally I much prefer ALL technical documentation (as opposed
to user documentation) of the code to be in the code. Why?
Simple, in my experience VERY few programmers have the
discipline to maintain external documents, so they quickly get
out of sync and become completely useless.

It is hard enough for most people to be diligent about
maintaining comments and documentation that *are* part of
the source code.

You really have to develop the exact opposite opinion from
"comments don't really matter and have no effect", and consider
that a bad spelling in a comment is a real bug :-) Sure a bad
spelling is not serious, but the attitude that will not
tolerate bad spelling in program comments is one that goes
along with a commitment to maintaining good internal
documentation.


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