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-Thread: 103376,81054609038e88e3 X-Google-Attributes: gid103376,public X-Google-Language: ENGLISH,ASCII-7-bit Path: g2news1.google.com!news2.google.com!fu-berlin.de!uni-berlin.de!not-for-mail From: Nick Roberts Newsgroups: comp.lang.ada Subject: Re: Literate Programming in Ada, AdaDoc, AdaBrowse Date: Mon, 11 Oct 2004 21:28:05 +0100 Message-ID: <2t08mmF1p0n19U1@uni-berlin.de> References: <2sqmccF1oit5sU1@uni-berlin.de> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Trace: news.uni-berlin.de +t585FabbaJ7iwRH9qZUwwpI8M8LUQ9QkNU8Mib0Tw9ePoJNo= User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.7.2) Gecko/20040803 X-Accept-Language: en-us, en In-Reply-To: <2sqmccF1oit5sU1@uni-berlin.de> Xref: g2news1.google.com comp.lang.ada:5053 Date: 2004-10-11T21:28:05+01:00 List-Id: Nick Roberts wrote: > Time for the latest hairbrained scheme from your uncle Nicky. > ... Thanks to everyone for your replies. I still feel that AdaDoc, AdaBrowse, and other suggested solutions don't quite do what I personally want. Maybe it's a bit 'horses for courses'. Anyway, I think I'm going to experiment with a program that, in effect, regenerates the web files from the source files. Except that I'll use normal Texinfo files for the 'web' files (with the addition of a few special macros). In the source files, each fragment will start with a comment that contains its title between two special symbols. The symbols will be a pair of =####= for a top-level fragment, a pair of =###= for the next level down, and so on. Within the Texinfo files, I'll use the @lpfrag macro, followed the fragment's name, to insert the actual text of a fragment (with sub-fragments reduced to references). This way, source files can be amended and recompiled without making something else invalid, and the Texinfo files (having been processed by my program) can be processed in the normal way to produce HTML or other formats. A source file will look like this: ~~~ =####= Overall program =####= =###= Mix the ingredients =###= ... mix =###= Bake them in oven =###= =##= Open oven door =##= ... open =##= Put things in oven =##= ... put in ~~~ The original Texinfo file might look like this: ~~~ Opening the oven door is easy, all you have to do is... @lpfrag Open oven door Mixing ingredients is tricky if you don't use the ... @lpfrag Mix the ingredients Putting things into the oven requires gloves ... @lpfrag Put things in oven Baking things in an oven takes steps, first ... @lpfrag Bake them in oven Making a cake ... @lpfrag Overall program ~~~ Which would be expanded into (something like) the following: ~~~ Opening the oven door is easy, all you have to do is... @verbatim Open oven door ... open @end verbatim Mixing ingredients is tricky if you don't use the ... @verbatim Mix the ingredients ... mix @end verbatim Putting things into the oven requires gloves ... @verbatim Put things in oven ... put in @end verbatim Baking things in an oven takes steps, first ... @verbatim Bake them in oven @lpref Open oven door @lpref Put things in oven @end verbatim Making a cake ... @verbatim Overall program @lpref Mix the ingredients @lpref Bake them in oven @end verbatim ~~~ Anyway, I'll experiment with this a bit. To be honest, I suspect it would be easier to write my processing program in a langauge such as Python or Perl. Any recommendations? (Gawk?) I do think that the documentation produced by this technique would be supplemented, perhaps very usefully, by the output of AdaDoc or AdaBrowse. -- Nick Roberts