Seeking help about Lout programming (while literate programming)

[basile . starynkevitch]

Hello All,

I'm a very bad Lout programmer. I would be interested by help, or at
least very well commented example of Lout style. Of course, I'm
concerned with the difficult part of Lout: galley and
cross-references. Otherwise, detailed guidelines and Lout programming
clichés would be helpful.

I'm porting the tango-weevil literate programming package to Lout. All
is ok, except for the necessary waavilout.lt lout style file. However,
I'm a very poor Lout programmer. And unfortunately, Lout (I'm using
the latest Lout v3.03) don't have any debugging facilities; the
DEBUG_ON compile-time flag -in Lout's makefile- and the -d* runtime
options (enabled by DEBUG_ON) are, according to Jeff Kingston and by
my bitter experience, only useful to debug Lout's (obfuscated) C code
(in the z01.c to z45.c files).

I feel that Lout should have better debugging facilities. I suggested
adding a @Message primitive, which echos its right argument to stdout
and returns @Null, but there isn't such a thing and I did'nt find how
to add it into the z*.c files (it seems that nearly all Lout
primitives are implemented in several C files!).

Jeff suggested adding debugging output into the produced document. But
I feel it's only working when galley-s and so on are right.

Here is the tentative weevil output in Lout for a code chunk (in
C). It uses cprint, @CP, and the embedded Lout comment feature in
Cprint (see section 11.4 of Lout3.03 user guide). A chunk C code is
output as several code blocks (each having a source line number) made
of a few (generally 4 C source lines).

To give you an idea, here is a C code chunk in a hello_l.lw
lout-weevil input file (@code <foo> is a tango/weevil directive for
defining a new code chunk named foo, up to the @endcode line. @<bar>
invokes a code chunk named bar; we have a few Lout before, passed
verbatim by weevil. For this mail message I indented the example by 3
spaces.

   @PP
   Here is my main routine:

   @code <Routines>

   @<Saying>

   int
   main(int argc,
        char *argv)
   {
   /* if no argument exit */
      if (argc<=0) {
         perror("*no argument*");
         exit(1);
      };
   /* first we just say hello */
      @<Output Hello>
   /* then we leave the program */
      @<Leave Program>
   /* and we do nothing */
      @<Do Nothing>
   }
   @endcode
 
Weevil-lout produces the following Lout output. Of course, this is
produced by C code and I could change the format (or add //@ChunkGap
directives for instance) as I wish.

   @PP 
   Here is my main routine:
   @TWChunk #+begin macro Routines
      @Name {Routines}
      @File {hello_l.lw}
      @SourceLine {96}
      @ProgLanguage {c}
      @Tag {.tw.hello_l.lw.Routines}
      @Code { @CP @Begin
   /*@@TWCodeBlock @Lineno{25} {*/
   /*@@TWChunkRef{.tw.hello_l.lw.Saying}*/

   int
   /address@hidden @TWCodeBlock @Lineno{29} {*/main(int argc,
        char *argv)
   {
   /* if no argument exit */
   /address@hidden @TWCodeBlock @Lineno{33} {*/   if (argc<=0) {
      perror("*no argument*");
      exit(1);
   };
   /address@hidden @TWCodeBlock @Lineno{37} {*//* first we just say hello */
      /*@@TWChunkRef{.tw.hello_l.lw.Output.Hello}*/
   /* then we leave the program */
      /*@@TWChunkRef{.tw.hello_l.lw.Leave.Program}*/
   /address@hidden @TWCodeBlock @Lineno{41} {*//* and we do nothing */
      /*@@TWChunkRef{.tw.hello_l.lw.Do.Nothing}*/
   }

   /address@hidden */
   @End @CP}
    @Using{
     @TWUse{perror}
     @TWUse{exit}
   }#end @Using
    @Declaring{
    @TWDecl{main}
   }#end @Declaring
   @TWEndChunk


Please notice that:

c2lout processes the @Code argument to be made of several @TWCodeBlock
chunks. I want them to be output consecutively, with the Lineno output
on the left of the code block.

Other chunk references are output as
@TWChunkRef{other-chunk-tag}. Chunk numbering should be done by Lout.

tango/weevilout produces cross-references tables, output as @Using and
@Declaring directives.

for your information, I am (or supposed to be ... my Lout
misunderstanding makes me very humble and feeling stupid) a computer
scientist (I have a PhD in AI) and speaks (more or less) fluently
several languages (including Prolog, Scheme, ML, PostScript, C++, C,
unix shell, OPS5, Smalltalk, etc). Unfortunately, all my (supposed to
be) computer culture is nearly useless in understanding Lout.

I believe that Lout has functional values (but they seems not to be
1rst class - no Lambda (or closure making) in (documented) Lout), lazy
evaluation, backtracking etc. Unfortunately, I don't see them
mentionned in Lout guides, and only a remote mention in Lout Design
paper.

I'm lacking a Lout programmer's guide for the computer programmer (ie
using computing and not typographical terms). Or at least a glossary.


Jeff Kingston is of course so familiar with Lout's way of thinking
that he just can't understand my misunderstanding. 

Of course, I've read Lout's user and expert guide several times, and
also the "Lout Design" paper (in Software Practice & Experience).


I'm becoming crazy. I spent a full working week reading and re-reading
Lout documents, trying (more or less blindly, and imitating Jeff's
examples) some Lout code, etc. I didn't succeed.


Unless I'll get some help I probably will give up this tango-weevil
porting to Lout. But I believe that I did most of the work
(understanding Tango/weevil internals and C programming).


Also, I'm interested about knowing who did some Lout programming. Of
course, the emphasis is not on typographical fancies stuff (eg boxing,
etc) but on layout and galleys. Did any one coded successfully his own
Lout style, eg by extending the toy layout? Does anyone have
guidelines about making complex lout macros and defs (eg which mixes
several printing, generate a table of content, do automatic numbering,
etc).


I can send by email all my patches and coding to anyone interested in
helping me (total tango/weevil is about 6000 lines, or 153Kbytes; I've
coded about 600 lines of Tangled C code and 200 lines of faulty lout
code).



Thanks for reading and for helping.

--

----------------------------------------------------------------------
Basile STARYNKEVITCH   ----  Commissariat a l Energie Atomique
DRN/DMT/SERMA * C.E. Saclay bat.470 * 91191 GIF/YVETTE CEDEX * France
fax: (33) 1- 69.08.85.68; phone: (33) 1- 69.08.40.66; homephone: (33) 1- 
46.65.45.53
email: address@hidden (redirected to address@hidden);  
----------------------------------------------------------------------

N.B. Any opinions expressed here are solely mine, and not of my organization.
N.B. Les opinions exprimees ici me sont personnelles et n engagent pas le CEA.

Please cite a **small pertinent part** of my mail in all answers
Veuillez citer une **petite partie pertinente** de mon courrier dans vos 
reponses