[Axiom-developer] Re: allprose missing file

[root]

> I like that. Does this mean that these volume would also contain all the 
> code? That is exacly what I'd like to see.

yes, each volume subsumes the code for those portions of the system.
i'm gradually "combing" the code into the files.

> Tim you are referring to the license problem. Well, I did not say that I 
> am unwilling to contribute to Axiom (even under BSD). I would be even 
> happy to work on that. Don't do everything alone.

nope. didn't worry about the license. but the code isn't applicable to
most of axiom's documentation because it contains no algebra.

> > the algebra volume is going to be different from the others but i'm
> > still pondering the structure.
> 
> I would prefer to have this openly discussed. In particular, the 
> structure for an API description (which is aldordoc.sty in ALLPROSE). I 
> would not like to invent yet another structure for the documentation. 
> There should be a good one and that should be fixed. It's a pity that 
> the language designers haven't thought about structuring the +++ 
> comments. It is high time NOW. aldordoc.sty is my suggestion.

we did think about it. in fact, i went thru all of the algebra (which
contained almost NO +++ or ++ comments at all and wrote them all into
a common format. i also modified the compiler to complain if you did
not include ++ comments on signatures. blame the cheesy comments on me.
but we were under a lot of time pressure because we were trying to 
finish up axiom, write a book, incorporate NAG's libraries, extending
the browser, rewriting the algebra, making it portable, etc so we
could give it to NAG.

commenting the algebra was a tedious exercise that took a long time
but is ultimately not the best (or a good, or even a useful)
solution. we need to make the latex documentation style such that we
can tag and autoextract the documentation for domains.

axiom used to have an "autodoc" facility that generated javadoc-like
information for the algebra. attached you'll find a few memos from
the pre-NAG days. 

i started to write a program that would regenerate the autodoc/javadoc
kind of domain information. the (non-)program is also attached.
autodoc only worked on VM/370 and was never ported. i have a copy
of the paper document which i can scan so you can see what it used
to do.

> 
> >> I looked through the sources but could not find a guideline of how 
> >> .pamphlet files should look like. Obviously, Tim, your intention was 
> >> that each file is a separate document (a complete LaTeX file with added 
> >> <<CHUNKS>>). Where is the pamphlet structure described?
> > 
> > there isn't a guideline yet. it's evolving as i discover and steal new
> > ideas (like allprose).
> 
> Well, if you like to "steal"... wouldn't it be better to invite me to 
> contribute? That would raise the manpower working on Axiom.

take the lead on the algebra book. each book has a standard preamble
so they all have the same "look and feel". i'll send that under a
separate file and explain the parts. (doing that turns out to be
the same work as writing the section on how to write axiom books).

badtim



==================================================================
"autodoc memo"
==================================================================
index to files: (file type boot unless specified)
 dinfo  - this file contains the functions that collect
          the information for the tex document and the
          hypertex pages.  The information is taken mostly
          from the lisp-libs, but some info comes from
          $constructorDataTable. once the information
          is found it is stored on hash table.
          in order for the hypertex browse to operatewith resonable
          speed, some of the hash table must be precomputed
          and stored as one file on disk, that is reread
          the first time a user starts up browse.
dhtex -   this file contains the functions needed to create
  the ht pages dynamically.
search -   this file creates the functions that take
   patterns and find the matching constructors, operations
   and keywords (using wildcards and case insensitive completion)
keyword - this small file contains the functions needed
   to separate the keywords out of the comments, and
   shove them appropriately into the hash table.
dtex  - this file formats the information into a file
   that can be latexed into a hard document
   its top level function in driver which takes
   the names of the constructors that we want the document of.
   ex driver('Aggregate, 'Integer, 'Matrix).
   driver can also be called with a "driverFile".
   i have been using "algebra files j" as my driver file.
   it lists the source files that contain the constructors
   that we wish to get an autodoc of.
   to do this give the command driver( ['driverFile,:'"ALGEBRA FILES J"])
   if a driver file is to be used then the function
   generatedatabaseforharddoc() must be invoked.
pfile - contains the functions needed to look at a driver file
  and extract the necessary info.
texidx - this was written by bob sutor.
  /index commands can be inserted in to latex text and
  then when the file is latexed, and IDX file is created which
  contains the info needed to make an index.
  the function processTeXIndexFile(input idx file, output tex file)
  takes the idx file and creates a tex file which can then be
  appended to the end of the actual autodoc tex file (just before
  the last line). then when the tex file is latexed againg,
  it will contain the index.
doctools - contains various functions that are needed
  by the other files and must be read in for anything to work
vmcut - contains functions that work on lispvm
rtcut - defindes the same functions to work on common lisp for unix
rtcut1.lisp  -this is a supplement to rtcut.boot it must also be
   read. As an added bonus, this file has a function that
   reads in all the needed bbin files on the rt , and
   warms up browse by reading the precomputed hash table
   from the disk.  (hash.lisp). the function is called
   helpstart(). (i hate capitalization).
 
----------
 
-----------
how to use
 browse -  see softdoc memo
 autodoc - see harddoc memo









==================================================================
"harddoc" -- instructions for axiom's javadoc-like automatic documenter
==================================================================
heres how you get autodoc tex manuals:
 
(this has only been run on vm) it would take forever on the rt
i only have had the patience to run it on vm at night or weekends

--disk boogie
gime newspad  k b
gime *yourname* A C  -- c or anywher free
--now you may want to copy some of your files from
--your regular disk (now c) to A ..like spadprof input
                                 .. or  profile xedit
gime tdisk 50 a
newspad nruntime
 
-> )read doctools boot j )quiet
-> )read dinfo    boot j )quiet

-> )read dtex     boot j )quiet
-> )read pfile    boot j )quiet
-> )read vmcut    boot j )quiet
 
---> )bo generatedatabaseforharddoc()
---> )bo driver  ['driverFile, : '"DOCFILS FILES J"]
--     --this means use DOCFILS FILES J as the list of files that
--     --contain the source files of the desired constructors
--     --DOCFILS FILES J contains ALL files (I hope) for
--     --the current system
-- 
--if you only want an autodoc for a subset of scratchpad
--you may either write  your own autodoc files file, or
--you may enter the constructor names by hand
ex  )bo driver ('Aggregate, 'HomogeneousAggregate, Matrix)
--if your autodoc is relatively small then
--you won't have to do all of the funny stuff
--with temporary disks
!!!!!!!!!!!UPDATE
the current system on vm does not have a file like DOCFILS which 
list the spad files with descriptiions, so i took the file
ITERP EXPOSED 
and got rid of comment lines, and lines with unexposed constructors
and called it HACK LIST. it is on my a disk.


you can make your own list like that and set the variable
$conListFile
to the file name 
example
)bo $conListFile := '"HACK LIST A"

if you call 
)bo tdoc()

then it looks at the $conListFile   to get the list of constructors to 
document.






-> )quit
 
--now you must run tex you must run it
--a couple times (3 to be safe) to get the
--table of contents and index correctly
vmtex  auto tex (quiet latex duplex asif modcut3
vmtex  auto tex (quiet latex duplex asif modcut3
vmtex  auto tex (quiet latex duplex asif modcut3

!!if vmtex reports errors, then you may have tweek the tex file by hand.
vm doesnt let me xedit very large files, so i resorted to ftp ing the 
file to an rt, editing it there and then sending it back.
(the problem i got was due to some constructors in catdef spad.
 where the word axioms appeared in the first column, but wasnt
 followed by an axiom list)


at this point you should have a file AUTO IDX A which must be
processed to be usable sooooo...
 
newspad nruntime
)read TEXIDX BOOT J )quiet
)bo autIdx()
)quit
 
now you should have a file AUTOIDX TEX A
this file must be put in to the file AUTO TEX A just before
the last line.
 
now issue
vmtex  auto tex (quiet latex duplex on modcut
vmtex  attle   tex j (quiet latex duplex on modcut
 
               --sometimes xedit bitches that it doesnt have
               --room to work ifso then you can use different
               --editor (ftp to rt and use vi)
               --or you'll have to tex the index separately
               --as follows:
----edit file
put at the beginning :
\documentstyle[twoside]{report}
\headsep=0in
\oddsidemargin=0in
\evensidemargin=0in
\topmargin=0in
\textwidth=6.5in
\footskip=1in
\footheight=0in
\textheight=8in
\raggedright
\parindent=0in
\begin{document}
--here goes the index
\end{document}
---- vmtex  autoidx tex (quiet latex duplex on modcut3
 
 
if you want you can specify the copy *num* option with the
vmtex commands to get numerous copies.
 
if there are any problems, track me down and shoot me
(just kiddin')
steve gortler
 



==================================================================
autodoc.lisp 
==================================================================
\documentclass{article}
\usepackage{axiom}
\begin{document}
\title{Autodoc}
\author{Tim Daly}
\maketitle
\begin{abstract}
We want to generate the reference information from axiom source
files automatically.
\end{abstract}
\eject
\tableofcontents
\eject
By design the chunk name has 3 fields. 
The first field is one of \{category, domain, package\}.
The second field is the abbreviation.
The third field is the full name.
This routine will return two lists, the first is the list of
abbreviations and the second is the list of full names.

We keep looping until we run out of input, at which point we
throw out of the loop and catch it here.
<<until done>>
  (catch 'done
@
We open the source file
<<open source file>>=
   (with-open-file (in sourcefile)
@
We read each line, trimming off trailing spaces
<<for each line do>>=
    (loop
     (setq expr (read-line in nil 'done))
     (when (eq expr 'done) (throw 'done nil))
     (setq expr (string-trim '(#\space) expr))
@
We look for lines that begin with a chunk name that
starts with package, domain, or category and end with an
equal sign (which indicates a chunk definition).
<<when package domain or category definition>>=
     (when 
      (and (> (length expr) 4)
           (or
            (string= "@<<pa" (subseq expr 0 4))
            (string= "@<<do" (subseq expr 0 4))
            (string= "@<<ca" (subseq expr 0 4)))
           (char= (elt expr (1- (length expr))) #\=))
@
We remove the 3 characters, two $>$ and an $=$ which make up the chunk name.
<<remove the trailing chunk characters>>=
      (setq expr (subseq expr 0 (- (length expr) 3)))
@
We get the third field from the string which is the long name.
<<capture the long name>>=
      (setq point (position #\space expr :from-end t :test #'char=))
@
We get the second field from the string which is the abbreviation.
<<capture the abbreviation>>=
      (setq mark
       (position #\space 
        (string-right-trim '(#\space)
         (subseq expr 0 (1- point))) :from-end t))
      (push (string-trim '(#\space) (subseq expr mark point)) names)))))
@
<<srcabbrevs>>=
(defun srcabbrevs (sourcefile)
 (let (in expr start end names longnames)
<<until done>>
<<open source file>>
<<for each line do>>
<<when package domain or category definition>>
<<remove the trailing chunk characters>>
<<capture the long name>>
      (format t "~a ~a ~a~%" expr point longnames)
<<capture the abbreviation>>
  (values names longnames))))

@
\section{Doit}
<<doit>>
(srcabbrevs "/new/patch38/src/algebra/acplot.spad.pamphlet")

@
\section{Autodoc}
<<autodoc>>=
<<srcabbrevs>>
<<doit>>
@
\section{Makefile}
<<*>>=
TANGLE=/usr/local/bin/NOTANGLE -t8 
WEAVE=/usr/local/bin/NOWEAVE -delay
LISP=/new/patch38/obj/linux/bin/lisp

all: code doc run

code: autodoc.lisp.pamphlet
        @${TANGLE} -Rautodoc autodoc.lisp.pamphlet >autodoc.lisp

doc: autodoc.lisp.pamphlet
        @${WEAVE} autodoc.lisp.pamphlet >autodoc.tex
        @latex autodoc.tex
        @latex autodoc.tex

run: autodoc.lisp
        @cat autodoc.lisp | ${LISP}

remake:
        @${TANGLE} autodoc.lisp.pamphlet >Makefile

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