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,FREEMAIL_FROM autolearn=ham autolearn_force=no version=3.4.4 X-Google-Thread: 103376,81054609038e88e3 X-Google-Attributes: gid103376,public X-Google-Language: ENGLISH,ASCII-7-bit Path: g2news1.google.com!news1.google.com!news.glorb.com!wn14feed!worldnet.att.net!attbi_s02.POSTED!53ab2750!not-for-mail From: "Steve" Newsgroups: comp.lang.ada References: <2sqmccF1oit5sU1@uni-berlin.de> Subject: Re: Literate Programming in Ada, AdaDoc, AdaBrowse X-Priority: 3 X-MSMail-Priority: Normal X-Newsreader: Microsoft Outlook Express 6.00.2800.1437 X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1441 Message-ID: NNTP-Posting-Host: 24.21.42.251 X-Complaints-To: abuse@comcast.net X-Trace: attbi_s02 1097378978 24.21.42.251 (Sun, 10 Oct 2004 03:29:38 GMT) NNTP-Posting-Date: Sun, 10 Oct 2004 03:29:38 GMT Organization: Comcast Online Date: Sun, 10 Oct 2004 03:29:38 GMT Xref: g2news1.google.com comp.lang.ada:4978 Date: 2004-10-10T03:29:38+00:00 List-Id: Just to share another hairbrained scheme regarding documentation. What I would like to see is a fancy programming editor that allows you to include text, graphics, spreadsheets, etc., in comments. A way to do this is to maintain the source code as text with special markers referencing the comments, and maintain the comments in a separate file or database. The approach has the advantage that the compiler doesn't have to deal with the comments and the source may be viewed without the comments using a different editor. It has the disadvantage that a special editor is required to edit the code along with the comments, and since the code and comments are in separate files, there is always potential of losing the comment files. The editor could be made to output the source with comments in a standard format: html, pdf, etc. I'm one of those guys that likes to draw a lot of diagrams describing code. It is often hard to assemble comments in code that do the diagram justice. Steve (The Duck) "Nick Roberts" wrote in message news:2sqmccF1oit5sU1@uni-berlin.de... > Time for the latest hairbrained scheme from your uncle Nicky. > > I've been struggling with the question of how best to do the documentation > accompanying open source Ada projects. It is especially important that the > maintenance (as well as user) documentation is present, usable, and itself > continuously maintainable, for this kind of project. [snip] > Comments welcome. > > -- > Nick Roberts