axiom-developer
[Top][All Lists]

 From: root Subject: [Axiom-developer] article "standard" header/footer Date: Sat, 26 Nov 2005 11:25:53 -0500

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

\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

\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
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