Edit detail for SandboxPamphletStyle revision 2 of 2

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.