axiom-developer
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Axiom-developer] 20080215.01.tpd.patch (++E examples)


From: daly
Subject: [Axiom-developer] 20080215.01.tpd.patch (++E examples)
Date: Fri, 15 Feb 2008 16:33:52 -0600

This patch adds a new layer of documentation ability to Axiom.

Essentially, prior to this patch, the command

(1) -> )display operations plot

gives the result as a series of modemaps, such as:

There are 12 unexposed functions called plot :
   [1] (D2,Symbol,Segment DoubleFloat) -> Plot from PlotFunctions1 D2
            if D2 has KONVERT INFORM
   [2] (D2,D2,Symbol,Segment DoubleFloat) -> Plot from PlotFunctions1 
            D2
            if D2 has KONVERT INFORM
   [3] (Plot3D,Segment DoubleFloat) -> Plot3D from Plot3D
   [4] ((DoubleFloat -> DoubleFloat),(DoubleFloat -> DoubleFloat),(
            DoubleFloat -> DoubleFloat),(DoubleFloat -> DoubleFloat),Segment 
            DoubleFloat,Segment DoubleFloat,Segment DoubleFloat,Segment 
            DoubleFloat) -> Plot3D
            from Plot3D
   [5] ((DoubleFloat -> DoubleFloat),(DoubleFloat -> DoubleFloat),(
            DoubleFloat -> DoubleFloat),(DoubleFloat -> DoubleFloat),Segment 
            DoubleFloat) -> Plot3D
            from Plot3D
   [6] (Plot,Segment DoubleFloat) -> Plot from Plot
   [7] ((DoubleFloat -> DoubleFloat),(DoubleFloat -> DoubleFloat),
            Segment DoubleFloat,Segment DoubleFloat,Segment DoubleFloat) -> 
            Plot
            from Plot
   [8] ((DoubleFloat -> DoubleFloat),(DoubleFloat -> DoubleFloat),
            Segment DoubleFloat) -> Plot
            from Plot
   [9] (List (DoubleFloat -> DoubleFloat),Segment DoubleFloat,Segment 
            DoubleFloat) -> Plot
            from Plot
   [10] (List (DoubleFloat -> DoubleFloat),Segment DoubleFloat) -> Plot
            from Plot
   [11] ((DoubleFloat -> DoubleFloat),Segment DoubleFloat,Segment 
            DoubleFloat) -> Plot
            from Plot
   [12] ((DoubleFloat -> DoubleFloat),Segment DoubleFloat) -> Plot from
            Plot


These modemaps, in the above example, come from 3 domains:
PlotFunctions1, Plot3D, and Plot. 

The modemaps give very specific information about particular
operations but it is often a challenge to use this information to
create a function call. It would be useful if there were examples for
each call, for instance, modemap [12] would be:

 fp:=(t:DFLOAT):DFLOAT +-> sin(t)
 plot(fp,-1.0..1.0)$PLOT



This patch enables us to decorate the algebra documentation with specific
examples for each function signature. (This will later be used in unit
test cases.) 

To create the above output, the plot function from the Plot domain
has new comment lines that begin with ++E (that is, example lines).
Thus the plot signature that generates the above output looks like:

     plot: (F -> F,R) -> %
      ++ plot(f,a..b) plots the function \spad{f(x)} 
      ++ on the interval \spad{[a,b]}.
      ++ 
      ++E fp:=(t:DFLOAT):DFLOAT +-> sin(t)
      ++E plot(fp,-1.0..1.0)$PLOT

and you can see that the ++E lines are collected and displayed by the
)display operations command.

So, after this patch is applied, we see the result:

(1) -> )display operations plot

There are 12 unexposed functions called plot :
   [1] (D2,Symbol,Segment DoubleFloat) -> Plot from PlotFunctions1 D2
            if D2 has KONVERT INFORM
   [2] (D2,D2,Symbol,Segment DoubleFloat) -> Plot from PlotFunctions1 
            D2
            if D2 has KONVERT INFORM
   [3] (Plot3D,Segment DoubleFloat) -> Plot3D from Plot3D
   [4] ((DoubleFloat -> DoubleFloat),(DoubleFloat -> DoubleFloat),(
            DoubleFloat -> DoubleFloat),(DoubleFloat -> DoubleFloat),Segment 
            DoubleFloat,Segment DoubleFloat,Segment DoubleFloat,Segment 
            DoubleFloat) -> Plot3D
            from Plot3D
   [5] ((DoubleFloat -> DoubleFloat),(DoubleFloat -> DoubleFloat),(
            DoubleFloat -> DoubleFloat),(DoubleFloat -> DoubleFloat),Segment 
            DoubleFloat) -> Plot3D
            from Plot3D
   [6] (Plot,Segment DoubleFloat) -> Plot from Plot
   [7] ((DoubleFloat -> DoubleFloat),(DoubleFloat -> DoubleFloat),
            Segment DoubleFloat,Segment DoubleFloat,Segment DoubleFloat) -> 
            Plot
            from Plot
   [8] ((DoubleFloat -> DoubleFloat),(DoubleFloat -> DoubleFloat),
            Segment DoubleFloat) -> Plot
            from Plot
   [9] (List (DoubleFloat -> DoubleFloat),Segment DoubleFloat,Segment 
            DoubleFloat) -> Plot
            from Plot
   [10] (List (DoubleFloat -> DoubleFloat),Segment DoubleFloat) -> Plot
            from Plot
   [11] ((DoubleFloat -> DoubleFloat),Segment DoubleFloat,Segment 
            DoubleFloat) -> Plot
            from Plot
   [12] ((DoubleFloat -> DoubleFloat),Segment DoubleFloat) -> Plot from
            Plot

Examples of plot from PlotFunctions1


Examples of plot from Plot3D


Examples of plot from Plot

 fp:=(t:DFLOAT):DFLOAT +-> sin(t)
 plot(fp,-1.0..1.0)$PLOT

(1) -> 

all that remains is to add ++E example lines to the remaining 10,000
functions.

Tim

=======================================================================
diff --git a/changelog b/changelog
index 50f94e0..94eac53 100644
--- a/changelog
+++ b/changelog
@@ -1,3 +1,7 @@
+20080215 tpd src/interp/format.boot add )d op documentation
+20080215 tpd src/algebra/plot add comment documentation
+20080210 tpd src/algebra/Makefile add plot help and input files for plot
+20080210 tpd src/algebra/plot add help and input files
 20080210 tpd zips/gcl-2.6.8pre.h.powerpc-macosx.defs.patch added
 20080209 tpd src/doc/book add Ei,En,Ei1,Ei2,Ei3,Ei4,Ei5,Ei6
 20080207 tpd Makefile fix GCLOPTS-CUSTRELOC for macosxppc
diff --git a/src/algebra/Makefile.pamphlet b/src/algebra/Makefile.pamphlet
index b11ba9c..d140609 100644
--- a/src/algebra/Makefile.pamphlet
+++ b/src/algebra/Makefile.pamphlet
@@ -2118,7 +2118,7 @@ SPADHELP=\
  ${HELP}/Octonion.help               ${HELP}/OneDimensionalArray.help \
  ${HELP}/Operator.help               ${HELP}/OrderedVariableList.help \
  ${HELP}/OrderlyDifferentialPolynomial.help \
- ${HELP}/PlaneAlgebraicCurvePlot.help \
+ ${HELP}/PlaneAlgebraicCurvePlot.help ${HELP}/Plot.help \
  ${HELP}/PartialFraction.help \
  ${HELP}/Permanent.help              ${HELP}/Permutation.help \
  ${HELP}/Polynomial.help             ${HELP}/Quaternion.help \
@@ -2183,7 +2183,7 @@ REGRESS=\
  OrderlyDifferentialPolynomial.regress \
  PartialFraction.regress \
  Permanent.regress              Permutation.regress \
- PlaneAlgebraicCurvePlot.regress \
+ PlaneAlgebraicCurvePlot.regress Plot.regress \
  Polynomial.regress             Quaternion.regress \
  RadixExpansion.regress         RealClosure.regress \
  RealSolvePackage.regress       RegularTriangularSet.regress \
@@ -2795,6 +2795,12 @@ ${HELP}/PlaneAlgebraicCurvePlot.help: 
${IN}/acplot.spad.pamphlet
            ${IN}/acplot.spad.pamphlet \
             >${INPUT}/PlaneAlgebraicCurvePlot.input
 
+${HELP}/Plot.help: ${IN}/plot.spad.pamphlet
+       @echo 7064 create Plot.help from ${IN}/plot.spad.pamphlet
+       @${TANGLE} -R"Plot.help" ${IN}/plot.spad.pamphlet >${HELP}/Plot.help
+       @-cp ${HELP}/Plot.help ${HELP}/PLOT.help
+       @${TANGLE} -R"Plot.input" ${IN}/plot.spad.pamphlet >${INPUT}/Plot.input
+
 ${HELP}/Polynomial.help: ${IN}/multpoly.spad.pamphlet
        @echo 7065 create Polynomial.help from ${IN}/multpoly.spad.pamphlet
        @${TANGLE} -R"Polynomial.help" ${IN}/multpoly.spad.pamphlet \
diff --git a/src/algebra/plot.spad.pamphlet b/src/algebra/plot.spad.pamphlet
index ea92ae6..81c4846 100644
--- a/src/algebra/plot.spad.pamphlet
+++ b/src/algebra/plot.spad.pamphlet
@@ -10,6 +10,101 @@
 \tableofcontents
 \eject
 \section{domain PLOT Plot}
+<<Plot.input>>=
+-- plot.spad.pamphlet Plot.input
+)spool Plot.output
+)set message test on
+)set message auto off
+)clear all
+--S 1 of 2
+fp:=(t:DFLOAT):DFLOAT +-> sin(t)
+--R
+--R   (1)  theMap(Closure)
+--R                                           Type: (DoubleFloat -> 
DoubleFloat)
+--E 1
+
+--S 2 of 2
+plot(fp,-1.0..1.0)$PLOT
+--R 
+--R
+--R   (2)  PLOT(x = (- 1.)..1.   y = (- 
0.8414709848078965)..0.8414709848078965)
+--R                               [- 1.,- 0.8414709848078965]
+--R                      [- 0.95833333333333337,- 0.81823456433427133]
+--R                      [- 0.91666666666666674,- 0.79357780324894212]
+--R                      [- 0.87500000000000011,- 0.76754350223602708]
+--R                      [- 0.83333333333333348,- 0.74017685319603721]
+--R                      [- 0.79166666666666685,- 0.7115253607990657]
+--R                      [- 0.75000000000000022,- 0.68163876002333434]
+--R                      [- 0.70833333333333359,- 0.65056892982223602]
+--R                      [- 0.66666666666666696,- 0.61836980306973721]
+--R                      [- 0.62500000000000033,- 0.58509727294046243]
+--R                      [- 0.5833333333333337,- 0.55080909588697013]
+--R                      [- 0.54166666666666707,- 0.51556479138264011]
+--R                      [- 0.50000000000000044,- 0.47942553860420339]
+--R                      [- 0.45833333333333376,- 0.44245407023325911]
+--R                      [- 0.41666666666666707,- 0.40471456356112506]
+--R                      [- 0.37500000000000039,- 0.3662725290860479]
+--R                       [- 0.3333333333333337,- 0.3271946967961526]
+--R                      [- 0.29166666666666702,- 0.28754890033552849]
+--R                      [- 0.25000000000000033,- 0.24740395925452324]
+--R                      [- 0.20833333333333368,- 0.20682955954864138]
+--R                      [- 0.16666666666666702,- 0.16589613269341538]
+--R                      [- 0.12500000000000036,- 0.12467473338522805]
+--R                    [- 8.3333333333333703E-2,- 8.3236916200310623E-2]
+--R                    [- 4.1666666666667039E-2,- 4.1654611386019461E-2]
+--R                   [- 3.7470027081099033E-16,- 3.7470027081099033E-16]
+--R                      [4.166666666666629E-2,4.1654611386018711E-2]
+--R                      [8.3333333333332954E-2,8.3236916200309874E-2]
+--R                        [0.12499999999999961,0.1246747333852273]
+--R                        [0.16666666666666627,0.16589613269341463]
+--R                        [0.20833333333333293,0.20682955954864066]
+--R                        [0.24999999999999958,0.24740395925452252]
+--R                        [0.29166666666666624,0.28754890033552777]
+--R                        [0.33333333333333293,0.32719469679615187]
+--R                        [0.37499999999999961,0.36627252908604718]
+--R                         [0.4166666666666663,0.4047145635611244]
+--R                        [0.45833333333333298,0.44245407023325839]
+--R                        [0.49999999999999967,0.47942553860420273]
+--R                        [0.5416666666666663,0.51556479138263944]
+--R                        [0.58333333333333293,0.55080909588696947]
+--R                        [0.62499999999999956,0.58509727294046177]
+--R                        [0.66666666666666619,0.61836980306973666]
+--R                        [0.70833333333333282,0.65056892982223535]
+--R                        [0.74999999999999944,0.68163876002333379]
+--R                        [0.79166666666666607,0.71152536079906514]
+--R                        [0.8333333333333327,0.74017685319603665]
+--R                        [0.87499999999999933,0.76754350223602663]
+--R                        [0.91666666666666596,0.79357780324894167]
+--R                        [0.95833333333333259,0.81823456433427078]
+--R                                 [1.,0.8414709848078965]
+--R                                                                   Type: 
Plot
+--E 2
+)spool
+)lisp (bye)
+@
+<<Plot.help>>=
+=========================================================================
+Plot examples
+=========================================================================
+
+The Plot (PLOT) domain supports plotting of functions defined over a
+real number system. Plot is limited to 2 dimensional plots.
+
+The function plot: (F -> F,R) -> % plots the function f(x) on the
+interval a..b. So we need to define a function that maps from 
+DoubleFloat to DoubleFloat:
+
+  fp:=(t:DFLOAT):DFLOAT +-> sin(t)
+
+and then feed it to the plot function with a Segment DoubleFloat
+
+  plot(fp,-1.0..1.0)$PLOT
+
+See Also:
+o )show Plot
+o $AXIOM/doc/src/algebra/plot.spad.dvi
+
+@
 <<domain PLOT Plot>>=
 )abbrev domain PLOT Plot
 ++ Author: Michael Monagan (revised by Clifton J. Williamson)
@@ -48,7 +143,12 @@ Plot(): Exports == Implementation where
 --% function plots
 
     plot: (F -> F,R) -> %
-      ++ plot(f,a..b) plots the function \spad{f(x)} on the interval 
\spad{[a,b]}.
+      ++ plot(f,a..b) plots the function \spad{f(x)} 
+      ++ on the interval \spad{[a,b]}.
+      ++ 
+      ++E fp:=(t:DFLOAT):DFLOAT +-> sin(t)
+      ++E plot(fp,-1.0..1.0)$PLOT
+
     plot: (F -> F,R,R) -> %
       ++ plot(f,a..b,c..d) plots the function \spad{f(x)} on the interval
       ++ \spad{[a,b]}; y-range of \spad{[c,d]} is noted in Plot object.
diff --git a/src/interp/format.boot.pamphlet b/src/interp/format.boot.pamphlet
index 10b1be7..7dca247 100644
--- a/src/interp/format.boot.pamphlet
+++ b/src/interp/format.boot.pamphlet
@@ -177,6 +177,31 @@ substInOrder(alist,x) ==
   alist is [[a,:b],:y] => substInOrder(y,SUBST(b,a,x))
   x
 
+@
+\subsection{reportOpSymbol}
+This function prints the modemaps for operations as a result of the
+user command for some operation foo:
+\begin{verbatim}
+  )d op foo
+\end{verbatim}
+
+We have enhanced this function to search the documentation for each
+domain and print any examples it finds by calling the sayExample 
+function. Because of the way the databases are currently organized
+the documentation is under each domain and is kept separate from
+the modemaps. Ideally we'd output the example immediately after
+the related modemap but I have yet to figure out how to do that.
+
+We need to know the name of the function (which the user supplied)
+and we need to know a list of all of the domains containing that
+function. This is collected using PUSHNEW into the domain list.
+
+Once we've processed all of the modemaps we have a set of the
+domain names. We walk across that set requesting the documentation
+strings for that domain. There are a list of documentation strings, 
+one for each exported function. We call sayExample on each element
+of the list. If sayExample finds an example it prints it.
+<<*>>=
 reportOpSymbol op1 ==
   op := (STRINGP op1 => INTERN op1; op1)
   modemaps := getAllModemapsFromDatabase(op,nil)
@@ -192,8 +217,12 @@ reportOpSymbol op1 ==
   sayNewLine()
   -- filter modemaps on whether they are exposed
   mmsE := mmsU := NIL
+  domlist := NIL
   for mm in modemaps repeat
-    isFreeFunctionFromMm(mm) or isExposedConstructor getDomainFromMm(mm) => 
mmsE := [mm,:mmsE]
+    dom := getDomainFromMm(mm)
+    PUSHNEW(dom,domlist)
+    isFreeFunctionFromMm(mm) or isExposedConstructor dom =>
+      mmsE := [mm,:mmsE]
     mmsU := [mm,:mmsU]
   if mmsE then
     sayMms(op,mmsE,'"exposed") where
@@ -210,8 +239,105 @@ reportOpSymbol op1 ==
   if mmsU then
     if mmsE then sayNewLine()
     sayMms(op,mmsU,'"unexposed")
+  for adom in domlist repeat  
+   doc := GETDATABASE(adom,'DOCUMENTATION)
+   docs := CDR(ASSOC(op,doc))
+   sayNewLine()
+   sayBrightly ['"Examples of ",op," from ",adom]
+   sayNewLine()
+   for export in docs repeat
+    sayExample(CADR(export),op)
   nil
 
+@
+\subsection{sayExample}
+This function expects 2 arguments, the documentation string and
+the name of the operation. It searches the documentation string for
+\verb|++E| lines. These lines are examples lines for functions. 
+They look like ordinary \verb|++| comments and fit into the ordinary
+comment blocks. So, for example, in the plot.spad.pamphlet file we
+find the following function signature:
+\begin{verbatim}
+    plot: (F -> F,R) -> %
+      ++ plot(f,a..b) plots the function \spad{f(x)} 
+      ++ on the interval \spad{[a,b]}.
+      ++ 
+      ++E fp:=(t:DFLOAT):DFLOAT +-> sin(t)
+      ++E plot(fp,-1.0..1.0)$PLOT
+\end{verbatim}
+This function splits out and prints the lines that begin with \verb|++E|.
+
+A minor complication of printing the examples is that the lines have
+been processed into internal compiler format. Thus the lines that read:
+\begin{verbatim}
+      ++E fp:=(t:DFLOAT):DFLOAT +-> sin(t)
+      ++E plot(fp,-1.0..1.0)$PLOT
+\end{verbatim}
+are actually stored as one long line containing the example lines
+\begin{verbatim}
+"\\indented{1}{plot(\\spad{f},{}a..\\spad{b}) plots the function
+ \\spad{f(x)}} \\indented{1}{on the interval \\spad{[a,{}b]}.}
+ \\blankline
+ \\spad{E} fp:=(t:DFLOAT):DFLOAT +-> sin(\\spad{t})
+ \\spad{E} plot(\\spad{fp},{}\\spad{-1}.0..1.0)\\$PLOT"
+\end{verbatim}
+
+This function finds examples and strips off the prefix \verb|\\spad{E}| 
+from the stored form and calls cleanupLine to get rid of the other noise.
+<<*>>=
+sayExample(docstring,op) ==
+ point := SEARCH('"{E}",docstring)
+ point => 
+  line := SUBSEQ(docstring,point+3)
+  while (mark:=SEARCH('"{E}",line)) repeat
+   mark > 0 =>
+    PRINC cleanupLine (SUBSEQ(line,0,mark-6))
+    sayNewLine()
+    line := SUBSEQ(line,mark+3)
+  PRINC cleanupLine(line)
+  sayNewLine()
+  sayNewLine()
+
+@
+\subsection{cleanupLine}
+This function expects example lines in internal format that has been
+partially processed to remove the prefix. Thus we get lines that look 
+like:
+\begin{verbatim}
+ fp:=(t:DFLOAT):DFLOAT +-> sin(\\spad{t}) 
+ plot(\\spad{fp},{}\\spad{-1}.0..1.0)\\$PLOT
+\end{verbatim}
+
+It removes all instances of \verb|{}|, and \verb|\|, and unwraps the
+\verb|spad{}| call, leaving only the argument.
+
+We return lines that look like:
+\begin{verbatim}
+ fp:=(t:DFLOAT):DFLOAT +-> sin(t)
+ plot(fp,-1.0..1.0)$PLOT
+\end{verbatim}
+which is hopefully exactly what the user wrote.
+
+<<*>>=
+cleanupLine(line) ==
+ while (point := SEARCH('"{}",line)) repeat
+  point =>
+   left := SUBSEQ(line,0,point)
+   right := SUBSEQ(line,point+2)
+   line := CONCATENATE('STRING,left,right)
+ while (point := SEARCH('"\",line)) repeat
+  point =>
+   left := SUBSEQ(line,0,point)
+   right := SUBSEQ(line,point+1)
+   line := CONCATENATE('STRING,left,right)
+ while (point := SEARCH('"spad{",line)) repeat
+  left  := SUBSEQ(line,0,point)
+  mark  := SEARCH('"}",line)
+  mid   := SUBSEQ(line,point+5,mark)
+  right := SUBSEQ(line,mark+1)
+  line  := CONCATENATE('STRING,left,mid,right)
+ line
+
 formatOpType (form:=[op,:argl]) ==
   null argl => unabbrev op
   form2String [unabbrev op, :argl]




reply via email to

[Prev in Thread] Current Thread [Next in Thread]