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

[root]

> I think, it's a good idea that you've posted this "standard". I hope it 
> is still in an "discussion" state. I had a quick look at it and there 
> are some parts where I would restructure a bit. For other parts I need 
> to make up my mind first, so this will take some time.

everything is always in the "discussion state" but sometimes i just
press ahead and try to keep things moving. the "standard" is changing
rapidly due to your allprose hacking. "quick consensus and running
code" as they say in the RFCs. 

> 
> Just one quick comment... there are several places where you use TeX 
> syntax. I'd prefer to promote LaTeX (it's \newpage instead of \eject).
> In fact I don't like to see \eject at all. It is the task of the .cls 
> file to decide on the pagebreaks --> So maybe "\documentclass{report}" 
> would be more appropriate.

\newpage is fine. i'm an old tex person so i tend to use $$, \eject, etc
without knowing that there are "new tex standards" and upgrades. until
someone takes the time to inform me i don't even know to look.

> What I have seen is that axiom.sty in some way includes the whole of 
> noweb.sty and adds some commands related to Axiom. I would rather like 
> to see a structure like
> 
> \documentclass{...}
> \usepackage{metaaxiom}
> \begin{document}
> ...
> \end{document}

well, i'm WAS planning to do a document-and-cleanup cycle on axiom.sty
so that (a) only the things that are used survive (there is cruft from
history in there (b) it formats nicely so i can append it to stand-alone
documents and (c) the macros are documented like everything else. i haven't
done that yet due to time. i did merge a couple macros from other packages
so that we could write axiom documents that only depend on 1 package and
we could include that package as part of the .pamphlet file. i hate
getting documents i can't format because the author hasn't included
ALL of the tree of .sty files. 

plus noweb (WAS) planned to go away in favor of an axiom
implementation that had different features (like support for .booklet
files which use an optional URL syntax in chunk names). that may still
happen but it is open for discussion.

> 
> where metaaxiom.sty (or whatever you call it) whould be the name of a 
> package that simply includes all the other packages that are needed. 
> Also makeidx and hyperref should appear inside metaaxiom.sty via
> 
> \RequirePackage{makeidx}
> 
> Please remove
> 
> \begin{thebibliography}{99}
> \bibitem{1} nothing
> \end{thebibliography}
> 
> It is old technology. We should promote BibTeX. It would be much easier 
> to maintain.

sigh. old technology again. ok. propose something different for the
bibliography. i started on the bibtex thing (there is a bibtex.pamphlet
the src/doc directory which would collect annotated bibtex references
so we could keep them in one place and have a fully documented bibliography.
if you suggest what you'd like to see we can figure out how to connect it
to the bibtex.pamphlet and then spread the new machinery all over axiom.

> 
> I'll write a follow-up later...
> 
> Anyway, I like the idea with \author{} and abstract. Maybe I should 
> learn about the term "executive overview". I am not quiet sure what 
> "executive" stands for in this phrase. Isn't it a kind of "Introduction" 
> what Martin wants? So what could possibly be the difference between 
> "Introduction" and "Executive Overview"?

i tried to figure out the \author of each file. the basic rules i used were
   (1) if the author's names appears in the file use them
   (2) if i knew who wrote the file credit them
   (3) if there were more than 5 authors use 'the axiom team'
   (4) default to 'the axiom team'
credits are, at best, a guess and should be corrected if we learn more.
personally i favor a very liberal credit policy, almost to the point of
"you touched it, you own it". if you start axiom and type:

 -> )credits

you'll see a list i maintain of all of the people who seem to have
contributed. having just done that now i see your name is not on that
list (i'll correct that in the next release). when time permits i run
back over my email and add new people.

re: "Introduction" and "Executive Overview"?

are you familiar with the dilbert cartoon? think of the pointy-haired
boss as your target audience.  an "Executive Overview" is written for
someone who first visits the file and has no clue what is going
on. calling it an "Introduction" tends to make people want to write 5
lines of documentation with a target audience of the experienced
user/developer. the intent is to assume much less knowledge in your
target audience.

the "book standard" is coming... it's been busy here at the circus.

t