Edit detail for SandboxPamphletStyle revision 1 of 2

changed:
-
This page describes how pamphlets should look like.

There are already some connected pages like  
PamphletFiles,
PamphletExample,
LiterateProgramming,
but there is not yet a clear guide of how to write pamphlets.
Even worse, it is not completely clear how the final Axiom sources should look like.

This page is an attempt to start a discussion that should end in a guide of how pamphlet files
should look like, how formal they should be, how much should be inside the pamphlet, and
how much could could be just references to other sources like books, articles, online articles, etc.

See also the email thread with subject "Pamphlet style (was: Literated VMLISP.LISP.PAMPHLET)":http://lists.nongnu.org/archive/html/axiom-developer/2006-09/msg00683.html .

Everyone is invited to add his/her vision for a pamphlet style or his/her experience with writing literate programs.
Just add your name and your thoughts, visions, experiences, links etc. in connection with literate programming.

* Ralf Hemmecke:

  - Any contribution to current legacy code that adds insight into the code. 
    No restriction is currently imposed on how the pamphlet should look like.
    Try to relate the code to existing books, articles, other software that is doing similar things.
    BibTeX file is preferred for that.

  - **Vision**: The Axiom CAS becomes an Axiom Journal, ie, a mixture of a traditional CAS and a traditional journal.
    Articles for the Axiom Journal (AJ) contain top scientific research accompanied with an implementation based
    on former contributions to the AJ.

  - Consequence of the above vision:

    - Pamphlet files cover a certain area of research and should give appropriate links to the literature.
      Links into the AJ itself or other freely accessible resources are preferred. 

    - In order to allow more complex contributions, pamphlet files can be grouped into pamphlet libraries.

    - As with journal articles, pamphlet file should be as formal as traditional journal articles, ie, contain
      definitions, theorems, and proofs. It is most likely that proofs will appear for the first time in a
      pamphlet.

    - Algorithms should be explained and proved as in common textbooks about algorithms, but instead of pseudocode
      pamphlet files contain Axiom code that can be compiled and executed.

    - There should be a common style file for the AJ that gives the output similar look. 
      Authors should, however, have the freedom to add any LaTeX package they like.

  - References to my own experience with literate programs.

    - "Emacs Aldor mode":http://www.risc.uni-linz.ac.at/people/hemmecke/aldor/aldor.el.nw

    - "LaTeX style file to achieve hyperlinks and indicies with simple commands":http://www.risc.uni-linz.ac.at/people/hemmecke/aldor/rhxterm.sty.nw

    - "ALLPROSE":http://www.risc.uni-linz.ac.at/people/hemmecke/aldor/allprose/

  - References to other literate programs. Usually, LaTeX packages are written in a literate programming style.

    - Look at "graphviz.dtx":http://people.csail.mit.edu/drayside/latex/graphviz.new/graphviz.dtx and "graphviz.pdf":http://people.csail.mit.edu/drayside/latex/graphviz.new/graphviz.pdf in "http://people.csail.mit.edu/drayside/latex/graphviz.new/":http://people.csail.mit.edu/drayside/latex/graphviz.new/

    - "doc.dtx":ftp://ftp.dante.de/tex-archive/macros/latex/base/doc.dtx and
      "docstrip.dtx":ftp://ftp.dante.de/tex-archive/macros/latex/base/docstrip.dtx or look at the many other
      LaTeX packages that come in literate form (extension .dtx) on "CTAN":http://ctan.org/ .

  - More references about literate programming in general

    - "Knuth: Literate Programming":http://www-cs-faculty.stanford.edu/~uno/lp.html

  - Some hints for writing pamphlets.

    - LaTeX (not plain TeX) is the preferred form, ie, use '\begin{blah} ... \end{blah}'
      to tag bigger regions of code.
      That makes transformation into other outputformats (especially html) easier.
 
    - Use '\usepackage{hyperref}' to produce hyperlinked documents. You might want to consider
      "rhxterm.sty":http://www.risc.uni-linz.ac.at/people/hemmecke/aldor/rhxterm.sty.nw since it
      allows \defineterm{some concept} and \useterm{some concept} and produces hyperlinks and
      index entries without much typing.

    - Use '\url{put url here}' to make an active link.

    - Describe algorithms in an abstract way that describe the essence of it. Take, for example
      the Gosper algorithm from the book "A=B":http://www.cis.upenn.edu/~wilf/AeqB.html (chapter 5, page 77).

      The algorithm approximately reads::

        1. Form the rational function r(n)=t(n+1)/t(n).
        2. Write r(n)=a(n)/b(n) * c(n+1)/c(n) where a,b,c satisfy (5.2.4)
        3. Find a nonzero polynomial solution x(n) of (5.2.6) or return "failed"
        4. Return b(n-1)*x(n)/c(n) * t(n).
      
      Then you see Section 5.3 "The full algorithm: Step 2".

      So as a pamphlet that should become::

        <<Gosper Algorithm>>=
        <<Form the rational function r(n)=t(n+1)/t(n).>>
        <<Write r(n)=a(n)/b(n) * c(n+1)/c(n) where a,b,c satisfy (5.2.4)>>
        <<Find a nonzero polynomial solution x(n) of (5.2.6) or return "failed">>
        <<Return b(n-1)*x(n)/c(n) * t(n).>>
        @

      As in "A=B" the steps (and the corresponding code) are explained in an extra chapter.

This page describes how pamphlets should look like.

There are already some connected pages like  
PamphletFiles,
PamphletExample,
LiterateProgramming,
but there is not yet a clear guide of how to write pamphlets.
Even worse, it is not completely clear how the final Axiom sources should look like.
This page is an attempt to start a discussion that should end in a guide of how pamphlet files
should look like, how formal they should be, how much should be inside the pamphlet, and
how much could could be just references to other sources like books, articles, online articles, etc.
See also the email thread with subject Pamphlet style (was: Literated VMLISP.LISP.PAMPHLET) .
Everyone is invited to add his/her vision for a pamphlet style or his/her experience with writing literate programs.
Just add your name and your thoughts, visions, experiences, links etc. in connection with literate programming.


Ralf Hemmecke:

Any contribution to current legacy code that adds insight into the code. 
    No restriction is currently imposed on how the pamphlet should look like.
    Try to relate the code to existing books, articles, other software that is doing similar things.
    BibTeX file is preferred for that.
Vision: The Axiom CAS becomes an Axiom Journal, ie, a mixture of a traditional CAS and a traditional journal.
    Articles for the Axiom Journal (AJ) contain top scientific research accompanied with an implementation based
    on former contributions to the AJ.
Consequence of the above vision:

Pamphlet files cover a certain area of research and should give appropriate links to the literature.
      Links into the AJ itself or other freely accessible resources are preferred. 
In order to allow more complex contributions, pamphlet files can be grouped into pamphlet libraries.
As with journal articles, pamphlet file should be as formal as traditional journal articles, ie, contain
      definitions, theorems, and proofs. It is most likely that proofs will appear for the first time in a
      pamphlet.
Algorithms should be explained and proved as in common textbooks about algorithms, but instead of pseudocode
      pamphlet files contain Axiom code that can be compiled and executed.
There should be a common style file for the AJ that gives the output similar look. 
      Authors should, however, have the freedom to add any LaTeX package they like.



References to my own experience with literate programs.

Emacs Aldor mode
LaTeX style file to achieve hyperlinks and indicies with simple commands
ALLPROSE



References to other literate programs. Usually, LaTeX packages are written in a literate programming style.

Look at graphviz.dtx and graphviz.pdf in http://people.csail.mit.edu/drayside/latex/graphviz.new/
doc.dtx and
      docstrip.dtx or look at the many other
      LaTeX packages that come in literate form (extension .dtx) on CTAN .



More references about literate programming in general

Knuth: Literate Programming



Some hints for writing pamphlets.

LaTeX (not plain TeX) is the preferred form, ie, use \begin{blah} ... \end{blah}
      to tag bigger regions of code.
      That makes transformation into other outputformats (especially html) easier.
Use \usepackage{hyperref} to produce hyperlinked documents. You might want to consider
      rhxterm.sty since it
      allows \defineterm{some concept} and \useterm{some concept} and produces hyperlinks and
      index entries without much typing.
Use \url{put url here} to make an active link.
Describe algorithms in an abstract way that describe the essence of it. Take, for example
      the Gosper algorithm from the book A=B (chapter 5, page 77).
      The algorithm approximately reads:
        1. Form the rational function r(n)=t(n+1)/t(n).
        2. Write r(n)=a(n)/b(n) * c(n+1)/c(n) where a,b,c satisfy (5.2.4)
        3. Find a nonzero polynomial solution x(n) of (5.2.6) or return "failed"
        4. Return b(n-1)*x(n)/c(n) * t(n).


      Then you see Section 5.3 "The full algorithm: Step 2".
      So as a pamphlet that should become:
        <<Gosper Algorithm>>=
        <<Form the rational function r(n)=t(n+1)/t(n).>>
        <<Write r(n)=a(n)/b(n) * c(n+1)/c(n) where a,b,c satisfy (5.2.4)>>
        <<Find a nonzero polynomial solution x(n) of (5.2.6) or return "failed">>
        <<Return b(n-1)*x(n)/c(n) * t(n).>>
        @


      As in "A=B" the steps (and the corresponding code) are explained in an extra chapter.

This is pdfeTeX, Version 3.141592-1.21a-2.2 (Web2C 7.5.4)
 \write18 enabled.
entering extended mode
(./5495360722038687433-18px.tex
LaTeX2e <2003/12/01>
Babel <v3.8d> and hyphenation patterns for american, french, german, ngerman, b
ahasa, basque, bulgarian, catalan, croatian, czech, danish, dutch, esperanto, e
stonian, finnish, greek, icelandic, irish, italian, latin, magyar, norsk, polis
h, portuges, romanian, russian, serbian, slovak, slovene, spanish, swedish, tur
kish, ukrainian, nohyphenation, loaded.
(/usr/share/texmf-tetex/tex/latex/base/article.cls
Document Class: article 2004/02/16 v1.4f Standard LaTeX document class
(/usr/share/texmf-tetex/tex/latex/base/size10.clo))
(/usr/share/texmf-tetex/tex/latex/amsmath/amsmath.sty
For additional information on amsmath, use the `?' option.
(/usr/share/texmf-tetex/tex/latex/amsmath/amstext.sty
(/usr/share/texmf-tetex/tex/latex/amsmath/amsgen.sty))
(/usr/share/texmf-tetex/tex/latex/amsmath/amsbsy.sty)
(/usr/share/texmf-tetex/tex/latex/amsmath/amsopn.sty))
(/usr/share/texmf-tetex/tex/latex/amsfonts/amsfonts.sty)
(/usr/share/texmf-tetex/tex/latex/amsfonts/amssymb.sty)
(/usr/share/texmf-tetex/tex/latex/amscls/amsthm.sty)
(/usr/share/texmf-tetex/tex/generic/xypic/xy.sty
(/usr/share/texmf-tetex/tex/generic/xypic/xy.tex Bootstrap'ing: catcodes,
docmode, (/usr/share/texmf-tetex/tex/generic/xypic/xyrecat.tex)
(/usr/share/texmf-tetex/tex/generic/xypic/xyidioms.tex)
 Xy-pic version 3.7 <1999/02/16>
 Copyright (c) 1991-1998 by Kristoffer H. Rose <krisrose@ens-lyon.fr>
 Xy-pic is free software: see the User's Guide for details.

Loading kernel: messages; fonts; allocations: state, direction,
utility macros; pictures: \xy, positions, objects, decorations;
kernel objects: directionals, circles, text; options; algorithms: directions,
edges, connections;  Xy-pic loaded)
(/usr/share/texmf-tetex/tex/generic/xypic/xyall.tex
 Xy-pic option: All features v.3.3
(/usr/share/texmf-tetex/tex/generic/xypic/xycurve.tex
 Xy-pic option: Curve and Spline extension v.3.7 curve, circles, loaded)
(/usr/share/texmf-tetex/tex/generic/xypic/xyframe.tex
 Xy-pic option: Frame and Bracket extension v.3.7 loaded)
(/usr/share/texmf-tetex/tex/generic/xypic/xycmtip.tex
 Xy-pic option: Computer Modern tip extension v.3.3
(/usr/share/texmf-tetex/tex/generic/xypic/xytips.tex
 Xy-pic option: More Tips extension v.3.3 loaded) loaded)
(/usr/share/texmf-tetex/tex/generic/xypic/xyline.tex
 Xy-pic option: Line styles extension v.3.6 loaded)
(/usr/share/texmf-tetex/tex/generic/xypic/xyrotate.tex
 Xy-pic option: Rotate and Scale extension v.3.3 loaded)
(/usr/share/texmf-tetex/tex/generic/xypic/xycolor.tex
 Xy-pic option: Colour extension v.3.3 loaded)
(/usr/share/texmf-tetex/tex/generic/xypic/xymatrix.tex
 Xy-pic option: Matrix feature v.3.4 loaded)
(/usr/share/texmf-tetex/tex/generic/xypic/xyarrow.tex
 Xy-pic option: Arrow and Path feature v.3.5 path, \ar, loaded)
(/usr/share/texmf-tetex/tex/generic/xypic/xygraph.tex
 Xy-pic option: Graph feature v.3.7 loaded) loaded))
(/usr/share/texmf-tetex/tex/latex/graphics/graphicx.sty
(/usr/share/texmf-tetex/tex/latex/graphics/keyval.sty)
(/usr/share/texmf-tetex/tex/latex/graphics/graphics.sty
(/usr/share/texmf-tetex/tex/latex/graphics/trig.sty)
(/usr/share/texmf-tetex/tex/latex/graphics/graphics.cfg)
(/usr/share/texmf-tetex/tex/latex/graphics/dvips.def)))
(/usr/share/texmf-tetex/tex/latex/tools/verbatim.sty)
(/usr/share/texmf-tetex/tex/latex/graphviz/graphviz.sty
(/usr/share/texmf-tetex/tex/latex/psfrag/psfrag.sty))
(/usr/share/texmf-tetex/tex/latex/sage/sagetex.sty
Writing sage input file 5495360722038687433-18px.sage
(./5495360722038687433-18px.sout)) (./5495360722038687433-18px.aux)
 LaTeX Error: Environment blah undefined.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
l.60 \begin{blah}
                  ... \end{blah}
 LaTeX Error: \begin{document} ended by \end{blah}.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
l.60 \begin{blah} ... \end{blah}
[1] (./5495360722038687433-18px.aux) )
(see the transcript file for additional information)
Output written on 5495360722038687433-18px.dvi (1 page, 224 bytes).
Transcript written on 5495360722038687433-18px.log.