axiom-developer
[Top][All Lists]

## [Axiom-developer] Re: article "standard" header/footer

 From: Ralf Hemmecke Subject: [Axiom-developer] Re: article "standard" header/footer Date: Tue, 29 Nov 2005 03:04:04 +0100 User-agent: Thunderbird 1.4 (X11/20050908)

Hi Tim,

root wrote:

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.



In ALLPROSE I have specifically introduced a "Convention" environment since I found myself using some conventions that were nowhere else documented. So the pamphlet standards should go into a section of the Axiom book (part documentation).


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.



Sorry, but I cannot completely agree here. I would NEVER include axiom.sty into the document. It would be duplication of code and hard to maintain.


I also do not agree to the goal that each file is ONE literate program and in some sense stand alone. I, therefore, think that "head" and "tail" should not be part of a file, just the things that are inside the \begin{document} ... \end{document}.


If you like a wrapper, write a little script like "document" which adds "head" and "tail" on the fly. You design them to be equal anyway.


Then, I don't see, why we need standards for "article" and standards for "book" and why they should/could differ.


The Axiom book consists of parts. Each part covers a certain area of Axiom. So a Part consists of some "executive summary" and then includes the code (ehm pamphlet) files that belong to that part.


So the focus is on providing the parts. In the spirit of ALLPROSE that could mean the following:

1) Write some chapters about the general idea.

Then a chapter that lists the files names (of the files that form the contents of the book) together with a short description of what the corresponding file contains. Then simply include all those files.


2) So there are several (about as many as there are parts) special files. I call them part.pamhlet files. All other files are ordinary pamphlet files.


3) Each pamphlet should be reasonably self-contained. In particular, a script could select several pamphlet files and compile them together into one document. (An "executive summary" could be missing if it is not explicitly included, but who cares?)


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

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



\begin{History}
\logitem{DATE1}{AUTHOR1} DESCRIPTION1
\logitem{DATE2}{AUTHOR2} DESCRIPTION2
\end{History}
\begin{abstract} ... \end{abstract}
\begin{ExecutiveSummary} ... \end{ExecutiveSummary}
\begin{Content} ... \end{Content}


If you like \title, no problem, but in the book it will probably translate into \chapter. In ALLPROSE, the filename is wrapped into a \section command via \nwfilename (generated by noweb).


The History could be translated into an \author command by LaTeX or a script. It does not mean that the History information shows in the book, but it would be in the file for those who dig that deep.


It would be \newenvironment{Content}{}{}, so it is a shield against redefining commands within that environment, but is not really necessary, since a script could add such an environment on the fly.


If you miss \tableofcontents above ... it is just a question of how the environment ExecutiveSummary is actually defined.

[snip-snap]


\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



I like the "sec:" part, but it should be clear that each section should have a unique label (over ALL Axiom files). Or we agree that a file can never reference outside its own file scope. (I don't like the latter idea.)


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


That is to LISP specific for me.


<<runtests>>=
test the foo function
@



For Aldor we have AldorUnit as a test environment, and it is not always clear whether the code that tests something is tightly connected to the domain(s) that is/are tested.


\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



Maybe you don't like it, but I use a slightly different approach in ALLPROSE. What comes out as defn and use in your case comes out in red and blue color in the index in ALLPROSE. And you would simply say: \defineterm{foo} and \useterm{foo}. Read the description of rhxterm.sty.nw on http://www.hemmecke.de/aldor. It even hyperlinks the foo in \useterm to the foo in \defineterm, not just putting something into the index.


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



If you like your LISP files that way, fine for me. I will not change the building and testing process.


=======================================================================
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}

@



No, I cannot follow. You mean the Makefile is part of the file that contains the LISP code?


I don't say it is generally a bad idea, but I cannot say that I like it. In particular, I don't see, why the variables TANGLE, WEAVE, etc. should be repeated in every file.


For the .dvi generation I rather like to write a script so that the inverse search becomes available.


By the way, you need "dummyindex" because you have \input{${PROJECT}.ind} below. \printindex is enough.   \eject \begin{thebibliography}{99} \bibitem{1} nothing \end{thebibliography} <<dummyindex>>= \begin{theindex} \item none \end{theindex} \printindex \input{${PROJECT}.ind}
\end{document}



The thebibliography environment is superfluous if we agree on ONE big .bib file and UNIQUE BibKeys. It is even more flexible.


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

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.



Aha, that means you have one "project" per file. May I ask what a "project" is in your case, in particular, how big it is?


 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.


My workflow for ALLPROSE is:

Type in a shell:

notangle -t8 Makefile.nw > Makefile
make dvi
xdvi myalps.dvi&
xemacs

Go in the dvi file to an interesting place.
Ctrl-MouseLeft

xemacs opens the corresponding .nw file exactly at the place corresponding to the dvi file.

-- .emacsrc
(global-set-key [f9] 'recompile)
(global-set-key [(control f9)] 'compile)
-- end .emacsrc

I edit something and type C-F9, enter "make; make dvi"
Next time just pressing F9 is enough.


If the Aldor compiler were a little better, I would even get the following in case my Aldor file contains an error.

-- .emacsrc
(global-set-key [f12] 'next-error)
(global-set-key [(shift f12)] 'previous-error)
(global-set-key [(control f12)] 'shell)
-- end .emacsrc


Press F12. Emacs opens the .nw file corresponding to the error message and jumps to the place where the error occured.

Ralf