diff --git a/books/bookvol4.pamphlet b/books/bookvol4.pamphlet index 8f1aaa7..6596b4a 100644 --- a/books/bookvol4.pamphlet +++ b/books/bookvol4.pamphlet @@ -4873,6 +4873,626 @@ function SVGscale(scale) { \end{verbatim} \section{Adding Algebra} +\subsection{Adding algebra to the books} +Assume you have a piece of algebra code that you want to permanently add +to Axiom. This is a fairly complex process since the system automatically +runs regression tests, creates help files, etc. and has other standard +features you need to support. Lets assume your algebra looks like this: +\begin{verbatim} +)abbreviation package INTERGB InterfaceGroebnerPackage +InterfaceGroebnerPackage(K,symb,E,OV,R):Exports == Implementation where + K : FIELD + symb : List Symbol + E : OrderedAbelianMonoidSup + OV : OrderedSet + R : PolynomialCategory(K,E,OV) + + LIST ==> List + + Exports ==> with + groebner: LIST R -> LIST R + + Implementation ==> add + PF ==> PrimeField(q) + DPF ==> DistributedMultivariatePolynomial(symb,PF) + D ==> DistributedMultivariatePolynomial(symb,K) + JCFGBPack ==> GroebnerPackage(PF,E,OV,DPF) + GBPack ==> GroebnerPackage(K,E,OV,D) + + coerceDtoR: D->R + coerceDtoR(pol) == map(#1,pol)$MPolyCatFunctions2(OV,E,E,K,K,D,R) + + groebner(l)== + ldmp:List D:= [coerceRtoD(pol) for pol in l] + gg:=groebner(ldmp)$GBPack + [coerceDtoR(pol) for pol in gg] + +\end{verbatim} + +There are some things to check and things to change. +\begin{itemize} +\item remove all tabs. Spad is a language that assigns meaning to +indentation and tabs are not going to survive the build process intact. +\item try to stay within 80 characters. Spad code is printed in the books +so it should try to limit line lengths everywhere. +\item change ``)abbreviation'' to ``)abbrev''. The Makefile will search +for the abbrev line and expect this exact text. +\begin{verbatim} +)abbrev package INTERGB InterfaceGroebnerPackage +\end{verbatim} +\item make sure there is only a single space between the items in the +abbrev line. The Makefile assumes this. +\item Add the comment header block. The author information is used to +check that all authors are included in the credits. The description +tag is used as output by the ``)describe'' command. For example: +\begin{verbatim} +++ Author: Gaetan Hache +++ Date Created: September 1996 +++ Date Last Updated: April, 2010, by Tim Daly +++ Description: +++ Part of the Package for Algebraic Function Fields in one variable PAFF +\end{verbatim} +Other tags can be included but are not used. Do not assume that any +format information will be correctly translated or preserved. Make the +description section be simple text with a single character between the +``++'' and the first word of the text. +\end{itemize} + +\begin{enumerate} +\item Choose the right book: +\begin{itemize} +\item Category goes into book bookvol10.2.pamphlet +\item Domain goes into book bookvol10.3.pamphlet +\item Package goes into book bookvol10.4.pamphlet +\item Numerics goes into book bookvol10.5.pamphlet +\end{itemize} +\item Find the right chapter. Chapter ordered by name, not abbreviation +\item Create a new section. The easiest way to do this is to copy another +section and change the names. In any case, your new section will need +\item Create a dividiing line consisting of all \% signs. +Note that this character is the comment character for TeX. +\item Create the \verb|\section| tag. This tag should contain the exact text of +the )abbrev line from your algebra code. In our case it would read: +\verb|)section{package INTERGB InterfaceGroebnerPackage}| +\item Create a regression test chunk. This chunk derives its name from the +algebra name as in ``InterfaceGroebnerPackage.input''. This chunk will +be automatically extracted and run during regression testing. For the +moment the chunk should be a simple empty input file as in: +\begin{verbatim} +)set break resume +)sys rm -f InterfaceGroebnerPackage.output +)spool InterfaceGroebnerPackage.output +)set message test on +)set message auto off +)clear all + +--S 1 of 1 +)show InterfaceGroebnerPackage +--E 1 + +)spool +)lisp (bye) +\end{verbatim} +\item Create a help text chunk. This chunk dervies its name from the +algebra name as in ``InterfaceGroebnerPackage.help''. This chunk will +be automatically extracted and used to build help text during build. +For the moment the chunck should be a simple empty help text file as in: +\begin{verbatim} +==================================================================== + examples InterfaceGroebnerPackage +==================================================================== + +See Also: +o )show InterfaceGroebnerPackage + +\end{verbatim} +\end{enumerate} + +At this point we need information from the Axiom interpreter to continue. +Start Axiom and compile your program with ``autoload'' on. For example: +\begin{verbatim} + axiom -nox + )set message autoload on + )co InterfaceGroebnerPackage.spad +\end{verbatim} + +You will see output containing lines which detail the category, domains, +and packages needed by your code, for example: +\begin{verbatim} + Loading /research/test/mnt/ubuntu/algebra/FIELD.o for category Field + + Loading /research/test/mnt/ubuntu/algebra/EUCDOM.o for category + EuclideanDomain + Loading /research/test/mnt/ubuntu/algebra/PID.o for category + PrincipalIdealDomain + Loading /research/test/mnt/ubuntu/algebra/GCDDOM.o for category + GcdDomain + Loading /research/test/mnt/ubuntu/algebra/INTDOM.o for category + IntegralDomain + Loading /research/test/mnt/ubuntu/algebra/COMRING.o for category + CommutativeRing + Loading /research/test/mnt/ubuntu/algebra/RING.o for category Ring + Loading /research/test/mnt/ubuntu/algebra/RNG.o for category Rng + Loading /research/test/mnt/ubuntu/algebra/ABELGRP.o for category + AbelianGroup + Loading /research/test/mnt/ubuntu/algebra/CABMON.o for category + CancellationAbelianMonoid + Loading /research/test/mnt/ubuntu/algebra/ABELMON.o for category + AbelianMonoid + Loading /research/test/mnt/ubuntu/algebra/ABELSG.o for category + AbelianSemiGroup + Loading /research/test/mnt/ubuntu/algebra/SETCAT.o for category + SetCategory + Loading /research/test/mnt/ubuntu/algebra/BASTYPE.o for category + BasicType + Loading /research/test/mnt/ubuntu/algebra/KOERCE.o for category + CoercibleTo + Loading /research/test/mnt/ubuntu/algebra/SGROUP.o for category + SemiGroup + Loading /research/test/mnt/ubuntu/algebra/MONOID.o for category + Monoid + Loading /research/test/mnt/ubuntu/algebra/LMODULE.o for category + LeftModule + Loading /research/test/mnt/ubuntu/algebra/BMODULE.o for category + BiModule + Loading /research/test/mnt/ubuntu/algebra/RMODULE.o for category + RightModule + Loading /research/test/mnt/ubuntu/algebra/ALGEBRA.o for category + Algebra + Loading /research/test/mnt/ubuntu/algebra/MODULE.o for category + Module + Loading /research/test/mnt/ubuntu/algebra/ENTIRER.o for category + EntireRing + Loading /research/test/mnt/ubuntu/algebra/UFD.o for category + UniqueFactorizationDomain + Loading /research/test/mnt/ubuntu/algebra/DIVRING.o for category + DivisionRing + Loading /research/test/mnt/ubuntu/algebra/OAMONS.o for category + OrderedAbelianMonoidSup + Loading /research/test/mnt/ubuntu/algebra/OCAMON.o for category + OrderedCancellationAbelianMonoid + Loading /research/test/mnt/ubuntu/algebra/OAMON.o for category + OrderedAbelianMonoid + Loading /research/test/mnt/ubuntu/algebra/OASGP.o for category + OrderedAbelianSemiGroup + Loading /research/test/mnt/ubuntu/algebra/ORDSET.o for category + OrderedSet + Loading /research/test/mnt/ubuntu/algebra/POLYCAT.o for category + PolynomialCategory + Loading /research/test/mnt/ubuntu/algebra/PDRING.o for category + PartialDifferentialRing + Loading /research/test/mnt/ubuntu/algebra/FAMR.o for category + FiniteAbelianMonoidRing + Loading /research/test/mnt/ubuntu/algebra/AMR.o for category + AbelianMonoidRing + Loading /research/test/mnt/ubuntu/algebra/CHARZ.o for category + CharacteristicZero + Loading /research/test/mnt/ubuntu/algebra/CHARNZ.o for category + CharacteristicNonZero + Loading /research/test/mnt/ubuntu/algebra/FRETRCT.o for category + FullyRetractableTo + Loading /research/test/mnt/ubuntu/algebra/RETRACT.o for category + RetractableTo + Loading /research/test/mnt/ubuntu/algebra/EVALAB.o for category + Evalable + Loading /research/test/mnt/ubuntu/algebra/IEVALAB.o for category + InnerEvalable + Loading /research/test/mnt/ubuntu/algebra/FLINEXP.o for category + FullyLinearlyExplicitRingOver + Loading /research/test/mnt/ubuntu/algebra/LINEXP.o for category + LinearlyExplicitRingOver + Loading /research/test/mnt/ubuntu/algebra/KONVERT.o for category + ConvertibleTo + Loading /research/test/mnt/ubuntu/algebra/PATMAB.o for category + PatternMatchable + Loading /research/test/mnt/ubuntu/algebra/PFECAT.o for category + PolynomialFactorizationExplicit + Loading /research/test/mnt/ubuntu/algebra/FFIELDC.o for category + FiniteFieldCategory + Loading /research/test/mnt/ubuntu/algebra/FPC.o for category + FieldOfPrimeCharacteristic + Loading /research/test/mnt/ubuntu/algebra/FINITE.o for category + Finite + Loading /research/test/mnt/ubuntu/algebra/STEP.o for category + StepThrough + Loading /research/test/mnt/ubuntu/algebra/DIFRING.o for category + DifferentialRing + + Loading /research/test/mnt/ubuntu/algebra/NNI.o for domain + NonNegativeInteger + Loading /research/test/mnt/ubuntu/algebra/INT.o for domain Integer +\end{verbatim} + +These are all of the algebra files on which your algebra depends. +Collect all of these names into a list: +\begin{verbatim} +FIELD.o EUCDOM.o PID.o GCDDOM.o INTDOM.o +COMRING.o RING.o RNG.o ABELGRP.o CABMON.o +ABELMON.o ABELSG.o SETCAT.o BASTYPE.o KOERCE.o +SGROUP.o MONOID.o LMODULE.o BMODULE.o RMODULE.o +ALGEBRA.o MODULE.o ENTIRER.o UFD.o DIVRING.o +OAMONS.o OCAMON.o OAMON.o OASGP.o ORDSET.o +POLYCAT.o PDRING.o FAMR.o AMR.o CHARZ.o +CHARNZ.o FRETRCT.o RETRACT.o EVALAB.o IEVALAB.o +FLINEXP.o LINEXP.o KONVERT.o PATMAB.o PFECAT.o +FFIELDC.o FPC.o FINITE.o STEP.o DIFRING.o +NNI.o INT.o +\end{verbatim} + +The algebra files are arranged into layers. Algebra in a given layer can +only depend on algebra in lower layers. So algebra in layer 4 can only +depend on algebra in layers 0 through 3. + +Your algebra depends on all of the above algebra so we first need to +answer the question ``What is the highest layer of algebra my code +depends upon''. + +To answer that question we need to know the layer of each of the above files. +This can be determined by searching the Makefile and finding the layer. +We do this here and annotate the above list, rearranged by layers: + +\begin{verbatim} +FIELD.o EUCDOM.o PID.o GCDDOM.o INTDOM.o +COMRING.o RING.o RNG.o ABELGRP.o CABMON.o +ABELMON.o ABELSG.o SETCAT.o BASTYPE.o KOERCE.o +SGROUP.o MONOID.o LMODULE.o BMODULE.o RMODULE.o +ALGEBRA.o MODULE.o ENTIRER.o UFD.o DIVRING.o +OAMONS.o OCAMON.o OAMON.o OASGP.o ORDSET.o +POLYCAT.o PDRING.o FAMR.o AMR.o CHARZ.o +CHARNZ.o FRETRCT.o RETRACT.o EVALAB.o IEVALAB.o +FLINEXP.o LINEXP.o KONVERT.o PATMAB.o PFECAT.o +FFIELDC.o FPC.o FINITE.o STEP.o DIFRING.o +NNI.o INT.o +\end{verbatim} + +We find that +\begin{verbatim} +layer 0 +EUCDOM.o GCDDOM.o INTDOM.o COMRING.o RING.o RNG.o ABELGRP.o CABMON.o ABELMON.o +ABELSG.o SETCAT.o BASTYPE.o KOERCE.o MONOID.o ENTIRER.o UFD.o DIVRING.o +POLYCAT.o KONVERT.o FFIELDC.o DIFRING.o NNI.o INT.o + +layer 1 +SGROUP.o LMODULE.o RMODULE.o ORDSET.o RETRACT.o IEVALAB.o FINITE.o STEP.o +PATMAB.o + +layer 2 +BMODULE.o OASGP.o PDRING.o CHARZ.o CHARNZ.o EVALAB.o LINEXP.o + +layer 3 +MODULE.o OAMON.o + +layer 4 +ALGEBRA.o OCAMON.o + +layer 5 +PID.o OAMONS.o + +layer 6 +FIELD.o AMR.o FRETRCT.o FLINEXP.o + +layer 7 +FAMR.o FPC.o + +layer 10 +PFECAT.o +\end{verbatim} + +So we know that our algebra belongs in layer 11 since it depends on +PFECAT which lives in layer 10. + +Now we have all of the information needed to add the algebra to the book. +We create a new section that contains the following parts: +\begin{itemize} +\item the \verb|\section{...}| header +\item the input file +\item the help file +\item the page head markup +\item the pagepic markup +\item the Exports section +\item the theory and discussion section +\item the algebra +\item the dot picture file information +\end{itemize} + +We've already explained most of the sections. Now we insert a chunk +for our algebra. The name of this chunk is important because the Makefile +will look for this exact chunk name. In our example case it looks like: +\begin{verbatim} +@<>= +\end{verbatim} +which is followed immediately by the algebra starting with the ``abbrev'' +command. + +Make sure that the section names, input file names, help file names, +and chunk names all reflect the new algebra names. + +Next we copy the chunkname to the bottom of the file as part of the +algebra chunk. + +The next piece to be handled is the ``pagepic'' tag. This inserts a +picture into the book which shows what files our algebra depends upon. +We do this using the graphviz dot program. + +We create a file that shows the graph relationship. Since our code +INTERGB depends on PFECAT we show that here. We create a line for our +code that looks like: +\begin{verbatim} +"INTERGB" [color="#FF4488",href="bookvol10.4.pdf#nameddest=INTERGB"] +\end{verbatim} + +This tells us the name of the node, the background color where +\begin{itemize} +\item \#4488FF is a category +\item \#88FF44 is a domain +\item \#FF4488 is a package +\item \#FF8844 is a numeric +\end{itemize} +(note the rotation of bytes) and the html link from the graph to +the position in the document so the user can click on the picture +and go to the source code. It names the book and the offset. + +We have the same information for PFECAT: +\begin{verbatim} +"PFECAT" [color="#4488FF",href="bookvol10.2.pdf#nameddest=PFECAT"] +\end{verbatim} + +We combine this information to create a picture file for the graphviz dot +program: +\begin{verbatim} +digraph pic { + fontsize=10; + bgcolor="#FFFF66"; + node [shape=box, color=white, style=filled]; + +"INTERGB" [color="#FF4488",href="bookvol10.4.pdf#nameddest=INTERGB"] +"PFECAT" [color="#4488FF",href="bookvol10.2.pdf#nameddest=PFECAT"] +"INTERGB" -> "PFECAT" + +} +\end{verbatim} + +Save this file into \verb|$AXIOM/books/pic|. Then run: +\begin{verbatim} +dot -Tps ps/v104interfacegroebnerpackage.ps +\end{verbatim} + +This will generate a postscript file +\verb|$AXIOM/books/ps/v104interfacegroebnerpackage.ps| + +Note that the pagepic name should be lower case as this is the name of +a file in the file system. Axiom uses only lower case names as files +to avoid the problem of mixed-case or ambiguous case file systems. + +The pagepic file is saved into a subdirectory (ps) under the books +directory. The file contains the name of the book (v104 is volume 10.4), +the name of the algebra in lowercase, and the extension of ps. + +Now we modify the pagepic tag in book volume 10.4 to read: + +\verb|\pagepic{ps/v104interfacegroebnerpackage.ps}{INTERGB}{1.00}| + +This tells us where to find the file, what the abbreviation for the +file will be, and the scale factor to use to display the file (1.00). + +We copy the body of the pic file to the book so we can easily +recreate the graphs: +\begin{verbatim} +@<>= +"INTERGB" [color="#FF4488",href="bookvol10.4.pdf#nameddest=INTERGB"] +"PFECAT" [color="#4488FF",href="bookvol10.2.pdf#nameddest=PFECAT"] +"INTERGB" -> "PFECAT" +@ +\end{verbatim} + +Next we return to the command line and get explicit information about +our new domain: +\begin{verbatim} + +(1) -> )show INTERGB + InterfaceGroebnerPackage(K: Field,symb: List Symbol,E: OrderedAbelianMonoidSup,OV: OrderedSet,R: PolynomialCategory(K,E,OV)) is a package constructor + Abbreviation for InterfaceGroebnerPackage is INTERGB + This constructor is exposed in this frame. + Issue )edit /research/silver/PAFF/PAFF/spad/interGBwoGB.spad to see algebra source code for INTERGB + +------------------------------- Operations -------------------------------- + groebner : List R -> List R + +\end{verbatim} + +We need to insert the results of this command into the trivial input file +we have created. The trivial input file will be run during build time and +the results of the command at build time will be compared with the results +we provide. The results we provide are actually comments so they begin with +two dashes, the Axiom comment character. + +The regression programm (``regress'') compares each line generated by the +program with the line stored in the input file. It only compares lines that +start with ``--R''. Each test is surrounded by the comment pair ``--S m of n'' +and ``--E m'' which indicates the start and end of test ``m'' respectively. + +Since we will eventually compile this domain from the book the final +output line for the )edit location will be the book. Thus we need to +change the line: +\begin{verbatim} +Issue )edit /PAFF/interGBwoGB.spad to see algebra source code for INTERGB +\end{verbatim} +to read: +\begin{verbatim} +Issue )edit bookvol10.4.pamphlet to see algebra source code for INTERGB +\end{verbatim} + +So we update our input file section to read: +\begin{verbatim} +)set break resume +)sys rm -f InterfaceGroebnerPackage.output +)spool InterfaceGroebnerPackage.output +)set message test on +)set message auto off +)clear all + +--S 1 of 1 +)show InterfaceGroebnerPackage +--R InterfaceGroebnerPackage(K: Field,symb: List Symbol,E: OrderedAbelianMonoidSup,OV: OrderedSet,R: PolynomialCategory(K,E,OV)) is a package constructor +--R Abbreviation for InterfaceGroebnerPackage is INTERGB +--R This constructor is exposed in this frame. +--R Issue )edit bookvol10.4.pamphlet to see algebra source code for INTERGB +--R +--R------------------------------- Operations -------------------------------- +--R groebner : List R -> List R +--R +--E 1 + +)spool +)lisp (bye) +\end{verbatim} + + +There is another section, Exports, which lists all of the unique function +names exported by this algebra. Note that this list is longer than just +the functions locally defined because the algebra inherits functions. +We make a tabular environment with the number of columns specified by +the ``l'' characters (``l'' means left-justify, ``c'' would be center, and +``r'' would be right justify). We include just enough columns to keep from +overflowing the 80 column limit. + +For this domain we see generate we only have a single export. +\begin{verbatim} +{\bf Exports:}\\ +\cross{INTERGB}{groebner} +\end{verbatim} + +The cross function creates a cross-reference entry in the index so you +can look up the function and find the domain or look up the domain and +find the function. + +Now we have finished setting up the algebra. + +We have to add the algebra, regression, and help information to the Makefile. + +We know from above that the algebra belongs in layer 11 so we find layer 11 +and add this abbreviation in alphabetical order. We can use this order since +none of the files depend on each other in this layer. +The new line looks like: +\begin{verbatim} + ${OUT}/INMODGCD.o ${OUT}/INNMFACT.o ${OUT}/INPSIGN.o ${OUT}/INTERGB.o \ +\end{verbatim} +Note that the trailing slash is required by the Makefile in order to continue +the input line. + +Take note of the prior algebra abbreviation INPSIGN. We search for that +lower down and find the block reading: +\begin{verbatim} +"INPSIGN" [color="#FF4488",href="bookvol10.4.pdf#nameddest=INPSIGN"] +/*"INPSIGN" -> {"RING"; "RNG"; "ABELGRP"; "CABMON"; "ABELMON"; "ABELSG"}*/ +/*"INPSIGN" -> {"SETCAT"; "BASTYPE"; "KOERCE"; "SGROUP"; "MONOID"}*/ +/*"INPSIGN" -> {"LMODULE"; "UPOLYC"; "POLYCAT"; "PDRING"; "FAMR"; "AMR"}*/ +/*"INPSIGN" -> {"BMODULE"; "RMODULE"; "COMRING"; "ALGEBRA"; "MODULE"}*/ +/*"INPSIGN" -> {"CHARZ"; "CHARNZ"; "INTDOM"; "ENTIRER"; "FRETRCT"}*/ +/*"INPSIGN" -> {"RETRACT"; "EVALAB"; "IEVALAB"; "FLINEXP"; "LINEXP"}*/ +/*"INPSIGN" -> {"ORDSET"; "KONVERT"; "PATMAB"; "GCDDOM"}*/ +"INPSIGN" -> "PFECAT" +/*"INPSIGN" -> {"UFD"; "ELTAB"; "DIFRING"; "DIFEXT"; "STEP"; "EUCDOM"}*/ +/*"INPSIGN" -> {"PID"; "FIELD"; "DIVRING"; "INT"; "INS-"}*/ +\end{verbatim} + +This information is used to create the total graph of the algebra. +Most of this information is kept for future graph use but commented out. +We only uncomment lines that are direct dependence relationships. As you +can see from the above INPSIGN depends only on PFECAT. + +First we create the signature line which is the same one used above for +the pagepic graph. + +We also need to create a similar block for our code. We use the list generated +above, replacing the ``.o'' with semicolons. + +The total result is: +\begin{verbatim} +"INTERGB" [color="#FF4488",href="bookvol10.4.pdf#nameddest=INTERGB"] +/*"INTERGB" -> { +/*"INTERGB" -> {"FIELD"; "EUCDOM"; "PID"; "GCDDOM"; "INTDOM"; "COMRING"}*/ +/*"INTERGB" -> {"RING"; "RNG"; "ABELGRP"; "CABMON"; "ABELMON"; "ABELSG"}*/ +/*"INTERGB" -> {"SETCAT"; "BASTYPE"; "KOERCE"; "SGROUP"; "MONOID"}*/ +/*"INTERGB" -> {"LMODULE"; "BMODULE"; "RMODULE"; "ALGEBRA"; "MODULE"}*/ +/*"INTERGB" -> {"ENTIRER"; "UFD"; "DIVRING"; "OAMONS"; "OCAMON"; "OAMON"}*/ +/*"INTERGB" -> {"OASGP"; "ORDSET"; "POLYCAT"; "PDRING"; "FAMR"; "AMR"}*/ +/*"INTERGB" -> {"CHARZ"; "CHARNZ"; "FRETRCT"; "RETRACT"; "EVALAB"}*/ +/*"INTERGB" -> {"IEVALAB"; "FLINEXP"; "LINEXP"; "KONVERT"; "PATMAB"}*/ +"INTERGB" -> "PFECAT" +/*"INTERGB" -> {"FFIELDC"; "FPC"; "FINITE"; "STEP"; "DIFRING"; "NNI"; "INT"}*/ +\end{verbatim} + +Now we add the help file. Look for the list called SPADHELP +(all help files live in \verb|$AXIOM/mnt/sys/doc/spadhelp|) +and add the full algebra name: +\begin{verbatim} + ${HELP}/InterfaceGroebnerPackage.help +\end{verbatim} + +Now we add the corresponding help stanza: +\begin{verbatim} +${HELP}/InterfaceGroebnerPackage.help: ${BOOKS}/bookvol10.4.pamphlet + @echo 7455 create InterfaceGroebnerPackage.help from \ + ${BOOKS}/bookvol10.4.pamphlet + @${TANGLE} -R"InterfaceGroebnerPackage.help" \ + ${BOOKS}/bookvol10.4.pamphlet \ + >${HELP}/InterfaceGroebnerPackage.help + @cp ${HELP}/InterfaceGroebnerPackage.help ${HELP}/INTERGB.help + @${TANGLE} -R"InterfaceGroebnerPackage.input" \ + ${BOOKS}/bookvol10.4.pamphlet \ + >${INPUT}/InterfaceGroebnerPackage.input + @echo "InterfaceGroebnerPackage (INTERGB)" >>${HELPFILE} +\end{verbatim} + +There are a couple things to note about the above stanza: +\begin{itemize} +\item the correct book needs to be referenced +\item the echo line should have a unique number +\item if a line exceeds 80 characters, split the line with a backslash +\item this stanza creates the input file for regression testing +\item this stanza creates 2 help files, one with the full algebra name +and one with the abbreviation so the user can query either one. +\item this stanza references chunk names in the book that have to exist +\end{itemize} + +Now we create the regression hook. Look for the list REGRESS and add the +line containing the algebra thus: +\begin{verbatim} + InterfaceGroebnerPackage.regress \ +\end{verbatim} + +This will cause regression to be run on the InterfaceGroebnerPackage.input +file. + +We need to modify book volume 5 (the interpreter) to add this algebra +to the list of exposed algebra. To do this, add the line: +\begin{verbatim} + (|InterfaceGroebnerPackage| . INTERGB) +\end{verbatim} +to the variable \verb|$globalExposureGroupAlist| under the ``basic'' +sublist. + +Now the algebra should build and have the new algebra available. +There are ways this can fail which we will cover in more detail. + +Once the code compiles cleanly there are a few ways to check that it works. +First, check that the file int/input/InterfaceGroebnerPackage.regress shows +no failures. Second, run the command +\begin{verbatim} + )show InterfaceGroebnerPackage +\end{verbatim} +to see if the domain exists. Run the command +\begin{verbatim} + )help InterfaceGroebnerPackage +\end{verbatim} +to see that the help file exists. Run the command +\begin{verbatim} + )describe InterfaceGroebnerPackage +\end{verbatim} +to see that the description paragraph exists. + +\subsection{Creating a stand-alone pamphlet file} Suppose we want to add a new algebra file from a new pamphlet. For example, we want to add BLAS1.spad in books/newbook.pamphlet. The explanation for the steps follow. The steps are: diff --git a/changelog b/changelog index 44dece4..d354f1b 100644 --- a/changelog +++ b/changelog @@ -1,3 +1,5 @@ +20100422 tpd src/axiom-website/patches.html 20100422.03.tpd.patch +20100422 tpd books/bookvol4 document process to add new algebra 20100422 tpd src/axiom-website/patches.html 20100422.02.tpd.patch 20100422 tpd books/bookvol10.5 fix missing INTERGB package 20100422 tpd src/axiom-website/patches.html 20100422.01.tpd.patch diff --git a/src/axiom-website/patches.html b/src/axiom-website/patches.html index 6dc0289..45058d5 100644 --- a/src/axiom-website/patches.html +++ b/src/axiom-website/patches.html @@ -2654,6 +2654,8 @@ books/bookvol10.4 add FiniteFieldFactorizationWithSizeParseBySideEffect
20100422.01.tpd.patch books/bookvol10.4 add InterfaceGroebnerPackage
20100422.02.tpd.patch -books/bookvol10.5 fix missing INTERGB package +books/bookvol10.5 fix missing INTERGB package
+20100422.03.tpd.patch +books/bookvol4 document process to add new algebra