[Axiom-developer] article "standard" header/footer

[root]

Ralf,

I promised to give you some idea of the pamphlet and book file coding
"standards". This is the current "state of the world" which evolves
as I write more pamphlet files. However, as I re-edit old files I
modify them to conform to these standards.

Each file I make into a "literate program" has a "head" and a "tail"
that contains essentially the same code for the same reasons. The only
major deviation is that I will occasionally include the "axiom.sty" file
in the literate document if it is meant to be stand-alone and the user
is unlikely to have it.

First, I've laid out the "head" and then a copy to explain it, 
Second I talk about labeling, index, naming, and testing conventions in
the body and, 
Third, I lay out the "tail" and a copy to explain it. 
Finally I explain the way I work with the literate programs.

So to start a project I open a file, insert the "head" and "tail"
code and then follow the conventions.

I'll send the book "standard" header/footer soon.





So, first, the standard "head" (for articles):

=======================================================================
\documentclass{article}               
\usepackage{axiom}
\usepackage{makeidx}
\makeindex
\begin{document}
\title{no title}
\author{Timothy Daly}
\maketitle
\begin{abstract}
\end{abstract}
\eject
\tableofcontents
\eject
\section{Executive Overview}
=======================================================================

and now the standard "head" with notes:

=======================================================================
\documentclass{article}

   The original Axiom layout had individual files each being a separate
   final .dvi file so article seemed appropriate. I still use this when
   I write a literate program that is intended to be stand-alone but
   Axiom is being rewritten into "book" class files.

\usepackage{axiom}

   The various latex format macros for Axiom live here. This is a
   collection of macros used in both the books and the articles.
   It also includes the latex macros used in noweb so there is no
   need to usepackage{noweb}

(another missing package is the hyperref package but i dont' yet know
 how to use it so it isn't included. but you've convinced me that it
 is a good idea so i plan to add it to all of the documentation after
 i understand how it works and how to write using it)

\usepackage{makeidx}
\makeindex

   Recent work by you has shown me the value of making an index so these
   have become part of my standard usage.

\begin{document}
\title{no title}
\author{Timothy Daly}
\maketitle

   Boilerplate headers

\begin{abstract}
\end{abstract}

   Since these are articles we need to write a few words for the casual
   browser so they can understand what the article is about.

\eject
\tableofcontents
\eject

   Boilerplate headers

\section{Executive Overview}

   Martin has convinced me that this needs to be in the front of every
   document. Literate programs are large, generally running into the
   hundreds of pages in my experience. This section is vitally necessary
   if you plan to make any progress in understanding the whole of it.

=======================================================================







within the article:

=======================================================================

\section{A section name}
\label{sec:Asectionname}

  section names have labels beginning with sec: so the \ref tag
  shows what it refers to. thus 
      \ref{sec:Asectionname}
  can be seen to refer to a section name


\subsection{defun foo}
\label{sec:defunfoo}
A discussion of the function foo.
\index{foo defun!defn}
<<defun foo>>
(defun foo () "whatever")

@
<<runtests>>=
  test the foo function

@


\subsection{defmacro bar}
\label{sec:defmacrofoo}
A discussion of the macro bar.
\index{bar defmacro!defn}
\index{foo defun!use}
<<defun bar>>
(defun bar () (foo))

@
<<runtests>>=
  test the bar macro

@

  defvars, defuns, defmacros, defstructs, etc all are at the subsection
  level so they show up in the table of contents. they also have the
  name of the function (first), that it is a function, and that this
  is the definition 
          \index{foo defun!defn}

  so they show up in the index looking like:

     foo defun
        defn   234
        use    442

     bar defmacro
        defn   442


\section{Code}
\label{sec:Code}
A discussion of the code block.
<<lisp>>=
<<defmacro bar>>
<<defun foo>>

<<runtests>>

@

  The Code section gathers all of the chunks together so they can be
  output into a file (see the makefile below)


  Test cases usually are in one chunk called <<runtests>> which get
  gathered together and added to the end of the <<lisp>> chunk. This
  allows me to automate the testing.



=======================================================================





and now the standard "tail":

=======================================================================
\section{Makefile}
<<*>>=
PROJECT=tpd
TANGLE=/usr/local/bin/NOTANGLE
WEAVE=/usr/local/bin/NOWEAVE
LATEX=/usr/bin/latex
LISP=/sei/lisp
MAKEINDEX=/usr/bin/makeindex

all: ${PROJECT}.lisp ${PROJECT}.dvi test

${PROJECT}.lisp: ${PROJECT}.pamphlet
        ${TANGLE} -Rlisp ${PROJECT}.pamphlet >${PROJECT}.lisp

${PROJECT}.dvi:
        ${TANGLE} -Rdummyindex ${PROJECT}.pamphlet >${PROJECT}.ind
        ${WEAVE} -t8 -delay ${PROJECT}.pamphlet >${PROJECT}.tex
        ${LATEX} ${PROJECT}.tex 
        @{MAKEINDEX} ${PROJECT}.idx
        ${LATEX} ${PROJECT}.tex 

test:
        cat ${PROJECT}.lisp | ${LISP}

remake:
        ${TANGLE} -t8 ${PROJECT}.pamphlet >Makefile.${PROJECT}

@
\eject
\begin{thebibliography}{99}
\bibitem{1} nothing
\end{thebibliography}
<<dummyindex>>=
\begin{theindex}
 \item none
\end{theindex}
\printindex
\input{${PROJECT}.ind}
\end{document}
=======================================================================

and now the standard tail with comments:

=======================================================================
\section{Makefile}
<<*>>=
PROJECT=tpd

  The project name is the same as the filename. The sequence for
  working is that I create a Makefile per project, in this case
  it would be:
                 Makefile.tpd
  and then i can set up an edit-test-debug cycle with
                 make -f Makefile.tpd


TANGLE=/usr/local/bin/NOTANGLE
WEAVE=/usr/local/bin/NOWEAVE
LATEX=/usr/bin/latex
LISP=/sei/lisp
MAKEINDEX=/usr/bin/makeindex

all: ${PROJECT}.lisp ${PROJECT}.dvi test

${PROJECT}.lisp: ${PROJECT}.pamphlet
        ${TANGLE} -Rlisp ${PROJECT}.pamphlet >${PROJECT}.lisp

   Here I extract the lisp code (chunk name <<lisp>>) to run.
   Of course, this varies with the project.

${PROJECT}.dvi:
        ${TANGLE} -Rdummyindex ${PROJECT}.pamphlet >${PROJECT}.ind

   We need an initial index file the first time we latex the project
   so we include a dummy index and extract it first. The dummy index
   lives at the end of the file under the chunk name <<dummyindex>>

        ${WEAVE} -t8 -delay ${PROJECT}.pamphlet >${PROJECT}.tex

   Here we extract the latex for the project

        ${LATEX} ${PROJECT}.tex 
        @{MAKEINDEX} ${PROJECT}.idx
        ${LATEX} ${PROJECT}.tex 

   and then we do the "latex 2-step" to get the dvi file with an index

test:
        cat ${PROJECT}.lisp | ${LISP}

   after we have the code and the documents we run the test cases.


remake:
        ${TANGLE} -t8 ${PROJECT}.pamphlet >Makefile.${PROJECT}

   and sometimes we make changes to the makefile chunk so we have a
   special stanza to "remake" the Makefile.${PROJECT}. The first time
   we have to extract the makefile by hand but after that we can just do:
        make -f Makefile.${PROJECT} remake
   and we get the updated makefile.

@
\eject
\begin{thebibliography}{99}
\bibitem{1} nothing
\end{thebibliography}

   more boilerplate

<<dummyindex>>=
\begin{theindex}
 \item none
\end{theindex}

   we create a dummy .ind file from this chunk so we can include it.
   if we don't do this then the first time we ever latex something
   it will fail.

\printindex

   this requests the index to be printed in the latex file.

\input{${PROJECT}.ind}

   and this includes the index so it is part of the document

\end{document}
=======================================================================




=======================================================================

and now the way I work with these:

=======================================================================


 notangle -t8 foo.pamphlet >Makefile.foo

    this extracts the default chunk <<*>>= which is a makefile and
    names it Makefile.foo.

 make -f Makefile.foo

    this completely rebuilds all of the foo project.

 emacs -nw foo.pamphlet
   (C-x 2     splits the emacs into 2 buffers, both visiting foo.pamphlet)
   (M-x shell starts a shell in one of the emacs buffers)

 in the shell I type:

   xdvi foo.dvi &

 which starts xdvi in a separate process. Every time I rebuild the .dvi file
 and give the focus to xdvi it rereads the .dvi file. So this allows me to
 keep the fully formatted file always available and up to date on the screen.

   (C-x o     switches between buffers)
   
 now I can edit the foo.pamphlet buffer and make changes. When I want to
 rebuild the file I do:

   (C-x o     switches between buffers (over to the *shell* buffer))
   make -f Makefile.foo
   (C-x o     switches between buffers (back to foo.pamphlet))

 and then slide the mouse over to the xdvi window and *poof* ... all
 of my file is newly formatted and the foo program is loaded and the
 tests are run.

 It's all very efficient. Of course, your mileage may vary.

Tim