[Axiom-developer] 20090227.03.tpd.patch (bookvol4: Hyperdoc tutorial)

[daly]

Add the tutorial for making new hyperdoc pages to 
Book Volume 4: Axiom Developers Guide
=======================================================================
diff --git a/books/bookvol4.pamphlet b/books/bookvol4.pamphlet
index 70d411d..d06e4c3 100644
--- a/books/bookvol4.pamphlet
+++ b/books/bookvol4.pamphlet
@@ -4420,6 +4420,53 @@ digraph pic {
 }
 \end{verbatim}
 
+\section{Adding or Editing pages in Hyperdoc}
+In Axiom it is easy to develop new pages in hyperdoc.
+All of the hyperdoc pages live in bookvol7.1.pamphlet.
+
+The structure of each page, say for the Fantastic domain, consists 
+of a few lines of latex followed by a literate chunk. All of the
+hyperdoc page information goes into the literate chunk and will
+be extracted as a hyperdoc page.
+
+\begin{verbatim}
+ \section{fantastic.ht}  <-- ordinary latex
+ \pagehead{FantasticPage}{fantastic.ht}{Fantastic} <-- special latex
+ \pageto{.....           <-- for latex (not hyperdoc) links to other pages
+ <<fantastic.ht>>=       <-- this is what htadd looks for
+
+   all the documentation for domain Fantastic
+
+ @                       <-- this is the end of the page for htadd
+\end{verbatim}
+
+When you add new pages to bookvol7.1.pamphlet you need to tell the
+system about the changes.  The ``htadd'' function will search the
+bookvol7.1.pamphlet file for chunks with the name ``*.ht'' and build the
+file ht.db.
+
+The ht.db file is used by hyperdoc to find pages. 
+Each line in ht.db contains a line that 
+
+\begin{verbatim}
+FantasticPage (byteIndex) (lineIndex)
+\end{verbatim}
+
+So the two critical files, bookvol7.1.pamphlet and ht.db live in \$AXIOM/doc
+
+
+There is a very fast cycle for editing.
+\begin{verbatim}
+cd $AXIOM/doc
+
+while (1) do
+   axiom                          <-- at the shell prompt
+   (navigate to page in hyperdoc) <-- to check your work
+   )lisp (bye)                    <-- at the axiom prompt
+   (modify bookvol7.1.pamphlet)   <-- change the page
+   rm ht.db                       <-- remove the old database
+   htadd bookvol7.1.pamphlet      <-- remake the database
+\end{verbatim}
 \section{Graphviz file creation}
 The graphviz output used on the website is a scaled vector graphics
 file (SVG). The dot command to output this file is:
diff --git a/src/axiom-website/patches.html b/src/axiom-website/patches.html
index 11a8e9f..c029a9f 100644
--- a/src/axiom-website/patches.html
+++ b/src/axiom-website/patches.html
@@ -975,5 +975,7 @@ input/Makefile remove bags.input<br/>
 bookvol10.3 document UnivariateSkewPolynomial<br/>
 <a href="patches/20090227.02.tpd.patch">20090227.02.tpd.patch</a>
 bookvol5 remove duplicate function<br/>
+<a href="patches/20090227.03.tpd.patch">20090227.03.tpd.patch</a>
+bookvol4 Hyperdoc tutorial on making new pages<br/>
  </body>
 </html>