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=-2.9 required=5.0 tests=BAYES_00,MAILING_LIST_MULTI autolearn=unavailable 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-26 17:45:27 PST Path: supernews.google.com!sn-xit-02!sn-xit-04!supernews.com!xfer13.netnews.com!netnews.com!opentransit.net!jussieu.fr!enst!enst.fr!not-for-mail From: "Robert C. Leif, Ph.D." Newsgroups: comp.lang.ada Subject: Increasing the readability of Ada was RE: Examples in Docs Date: Fri, 26 Jan 2001 17:43:59 -0800 Organization: ENST, France Sender: comp.lang.ada-admin@ada.eu.org Message-ID: Reply-To: comp.lang.ada@ada.eu.org NNTP-Posting-Host: marvin.enst.fr Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit X-Trace: avanie.enst.fr 980559926 63606 137.194.161.2 (27 Jan 2001 01:45:26 GMT) X-Complaints-To: usenet@enst.fr NNTP-Posting-Date: Sat, 27 Jan 2001 01:45:26 +0000 (UTC) To: Return-Path: X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.2416 (9.0.2911.0) Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V5.50.4522.1200 In-reply-to: <94c73f$hs9$1@nnrp1.deja.com> Errors-To: comp.lang.ada-admin@ada.eu.org X-BeenThere: comp.lang.ada@ada.eu.org X-Mailman-Version: 2.0 Precedence: bulk List-Help: List-Post: List-Subscribe: , List-Id: comp.lang.ada mail<->news gateway List-Unsubscribe: , List-Archive: Errors-To: comp.lang.ada-admin@ada.eu.org X-BeenThere: comp.lang.ada@ada.eu.org Xref: supernews.google.com comp.lang.ada:4590 Date: 2001-01-26T17:43:59-08:00 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/