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}
=======================================================================
What about just...
\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
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
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
_______________________________________________
Axiom-developer mailing list
Axiom-developer@nongnu.org
http://lists.nongnu.org/mailman/listinfo/axiom-developer