Greg, I used the ++(letter) and --(letter) form for various things.
++X is used for algebra examples as shown above These lines are output from )d op foo showing the user how to construct valid input to the function foo. This is useful because it is hard to guess how to contruct input of the required type. Since there are many functions with the same name there will be many examples, each associated with one function. In input files (src/input) they are decorated with --S n of m which gives the number of the test, e.g. 5 of 23 indicating starting a new test --R which gives the expected result (usually many --R lines) --I which tells the test comparison to ignore that line (e.g. when gensyms occur) --E n which ends the test n This allows the test to run ignoring the --(number) decoration and output the result. Then a program runs over the output (which includes the -- comments) and does a text comparison of the expected result --R with the actual result. For example -- factorization of polynomials over finite fields --S 5 of 21 u:UP(x,PF(19)) :=3*x^4+2*x^2+15*x+18 --R --R --R 4 2 --R (5) 3x + 2x + 15x + 18 --R Type: UnivariatePolynomial(x,PrimeField(19)) --E 5 --S 6 of 21 factor u --R --R --R 3 2 --R (6) 3(x + 18)(x + x + 8x + 13) --R Type: Factored(UnivariatePolynomial(x,PrimeField(19))) --E 6 Creating new tests amounts to running an expression then decorating the output with --R lines surrounded by the --S and --E boundaries. Creating tests is a simple text edit. Failing tests are indentified by file and test number showing both the computed and expected results. --U is an external URL marker used to link to a paper that contains the algorithm. For example, about Groebner Basis: --U https://www.amazon.com/Computational-Algebraic-Geometry-Groebner-Basis/dp/3659435856 --P was intended to jump to the PDF output in the literate program so a user could directly access the function sources in the correct domain along with the literate explanation. In general since ++ and -- comments are ignored the ++(letter) and --(letter) make it easy to add information that does not need compiler support. Tim ++ On Sun, Jun 15, 2025 at 12:44 PM Grégory Vanuxem <g.vanu...@gmail.com> wrote: > I have deleted my mails, sorry. But something like: > > 7) -> jlDocumentation mod <TAB> <TAB> > modTree modifyPointData modularFactor > modularLambda moduleSum > mod_exp modpeval modularGcdPrimitive > modular_compose moduloP > modifyPoint modpreduction modularInvariantJ module > modulus > > (7) -> jlDocumentation moduleSum > > moduleSum(m1, m2) returns the sum of two modules in the framed > algebra F. Each module mi is represented as fol > lows: F is a framed algebra with R-module basis w1, w2, ..., wn and > mi is a record [basis, basisDen, basisInv] > . If basis is the matrix (aij, i = 1..n, j = 1..n), then a basis v1, > ..., vn for mi is given by vi = (1/basisD > en) * sum(aij * wj, j = 1..n), i.e. the ith row of 'basis' contains > the coordinates of the ith basis vector. S > imilarly, the ith row of the matrix basisInv contains the > coordinates of wi with respect to the basis v1, ..., > vn: if basisInv is the matrix (bij, i = 1..n, j = 1..n), then wi = > sum(bij * vj, j = 1..n). From: IntegralBas > isTools > > > > Type: Void > (7) -> jlDocumentation mod <TAB><TAB> > modTree modifyPointData modularFactor > modularLambda moduleSum > mod_exp modpeval modularGcdPrimitive > modular_compose moduloP > modifyPoint modpreduction modularInvariantJ module > modulus > (7) -> jlDocumentation modpreduction > > > modpreduction(r, p) reduces a rational function r modulo prime p. > From: PolynomialEvaluationUtilities > > > modpreduction(p, q) reduces all coefficients of p modulo q. From: > ModularEvaluationCategory > > > modpreduction(pol, p) reduces polynomial pol modulo prime p. From: > PolynomialEvaluationUtilities > > > > Type: Void > > That uses a regular expressions system, sorry, strings are very bad > handled in panAxiom. But just that's would be very handy. > > BTW: Timothy, your 'X' is already implemented in HyperTex with: > > ++ For example, using JLMatrix(JLObjFloat64): > ++ \example{M:=nrand(4,4);} > ++ \example{jlApply("svd", M::JLMatrix(JLObjFloat64)).S} > ++ should be "equivalent" to svdvals(M) > > Maybe I do not understand your 'X'. > > BTW2: All my reconnaissance, of course, Tim. > > Cheers, > > Greg > > > > Le jeu. 12 juin 2025 à 12:32, Tim Daly <axiom...@gmail.com> a écrit : > > > > Taking the idea from Ralf it seems that there could be a "hyperdoc" > domain > > that implements all of the functions necessary to create user > documentation > > with both text output and HTML output forms. From that domain it should > > be possible to re-create Hyperdoc in a browser. > > > > > > > > On Thursday, June 12, 2025 at 6:29:38 AM UTC-4 Tim Daly wrote: > >> > >> Within algebra documentation for a function there are ++ and -- comments > >> The ++ comments are intended as documentation. > >> > >> I have extended the meaning of ++ comments by appending a single letter. > >> For example in the 'map' function from 'StreamFunction3' you'll see > >> > >> map : ((A,B) -> C,ST A,ST B) -> ST C > >> ++ map(f,st1,st2) returns the stream whose elements are the > >> ++ function f applied to the corresponding elements of st1 and > st2. > >> ++ \spad{map(f,[x0,x1,x2,..],[y0,y1,y2,..]) = > [f(x0,y0),f(x1,y1),..]}. > >> ++ > >> ++S > >> ++X m:=[i for i in 1..]::Stream(Integer) > >> ++X n:=[i for i in 1..]::Stream(Integer) > >> ++X f(i:Integer,j:Integer):Integer == i+j > >> ++X map(f,m,n) > >> > >> The ++X comments are part of the output shown during display functions, > e.g. > >> > >> )d op map > >> > >> will show the ++X comments as "examples" of how to use the function. > >> > >> There is also the 'ApplicationProgramInterface' which allows user-level > access > >> to various data structures: > >> > >> )abbrev package API ApplicationProgramInterface > >> ++ Author: Timothy Daly, Martin Rubey > >> ++ Date Created: 3 March 2009 > >> ++ Date Last Updated: 24 March 2012 > >> ++ Description: > >> ++ This package contains useful functions that expose Axiom system > internals > >> > >> ApplicationProgramInterface() : SIG == CODE where > >> > >> SIG ==> with > >> > >> getDomains : Symbol -> Set Symbol > >> ++ getDomains(s) takes a category and returns the list of domains > >> ++ that have that category > >> ++ > >> ++X getDomains 'IndexedAggregate > >> > >> getAncestors : Symbol -> Set Symbol > >> ++ getAncestors(s) takes a category and returns the list of > domains > >> ++ that have that category as ancestors > >> ++ > >> ++X getAncestors 'IndexedAggregate > >> > >> credits : () -> Void > >> ++ credits() prints a list of people who contributed to Axiom > >> ++ > >> ++X credits() > >> > >> summary : () -> Void > >> ++ summary() prints a short list of useful console commands > >> ++ > >> ++X summary() > >> > >> reportInstantiations : Boolean -> Void > >> ++ reportInstantiations(bool) is a debugging tool to show > >> ++ instantiation information > >> ++ > >> ++X reportInstantiations(true) > >> ++X 1 > >> ++X reportInstantiations(false) > >> > >> CODE ==> add > >> > >> getDomains(cat:Symbol):Set(Symbol) == > >> set [symbol car first destruct a _ > >> for a in (destruct > domainsOf(cat,NIL$Lisp)$Lisp)::List(SExpression)] > >> > >> getAncestors(cat:Symbol):Set(Symbol) == > >> set [symbol car first destruct a _ > >> for a in (destruct > ancestorsOf(cat,NIL$Lisp)$Lisp)::List(SExpression)] > >> > >> credits() == ( credits()$Lisp ; void() ) > >> > >> summary() == ( summary()$Lisp ; void() ) > >> > >> reportInstantiations(b:Boolean): Void == > >> REPORTINSTANTIATIONS(b)$Lisp > >> void > >> > >> > >> > >> > >> On Thu, Jun 12, 2025 at 5:06 AM Grégory Vanuxem <g.va...@gmail.com> > wrote: > >>> > >>> Hello, > >>> > >>> > >>> Le mer. 11 juin 2025 à 20:59, 'Ralf Hemmecke' via FriCAS - computer > >>> algebra system <fricas...@googlegroups.com> a écrit : > >>> > > >>> > Hi Waldek, > >>> > > >>> > as you know, I would like to let HyperDoc die. > >>> > But, maybe that sound too extreme for what I actually mean. > >>> > And I agree to some extend to your plan for a new hyperdoc. > >>> > > >>> > Let me explain my wishes. > >>> > > >>> > FriCAS should have an interface (in LISP or SPAD) that let's > >>> > SPAD or external programs get information about > >>> > categories/domains/packages/documentation. > >>> > From such an interface it should be easy to generate any output > format > >>> > be it html, rst or pdf. > >>> > >>> +1 > >>> > >>> For what I am interested in right now, is displaying '++' > >>> documentation in text form, and. readable directly in the interpreter > >>> console. > >>> From what I have read in api.spad and api2.spad the implementations > >>> are tightly related the reST and HTML formats and I would like > >>> plain/text format also. I do not want to use a Regex style replacement > >>> method as it requires Julia or cl-ppcre and/or, for my concern, > >>> cl-ppcre-unicode. Looking at api2 for example there is code to return > >>> TexTree as a SEX expression. There is a TeXTree to HTML converter > >>> which outputs the conversion in a file, no routine from what I have > >>> seen that converts it to a String. I will eventually code something in > >>> this regard. Maybe Waldek, you have already done this privately? > >>> Having a generic parser would be a very good idea, I think. Gathering > >>> the two parser implementations. > >>> > >>> > >>> jlDocumentation(op) == > >>> ops := getDatabase("o")$OperationsQuery > >>> docs := elt(ops,equation('name, op)$QueryEquation) > >>> elts : DataList(String) := elt(docs,'doc) > >>> for i in 1 .. #elts repeat > >>> output((elts.i)::OutputForm)$OutputPackage > >>> -- PPRINT(jlEvalString(concat(["replace(raw_"", > >>> > >>> "\spad{svd(m)} computes the singular value decomposition \spad{SVD} > of \spad{ > >>> m} such that \spad{SVD}.\spad{U} * diagonalMatrix(\spad{sv}) * > \spad{SVD}.\sp > >>> ad{Vt} = \spad{m}." > >>> "\spad{svd(m)} computes the singular value decomposition \spad{SVD} > of \spad{ > >>> m} such that \spad{SVD}.\spad{U} * diagonalMatrix(\spad{sv}) * > \spad{SVD}.\sp > >>> ad{Vt} = \spad{m}." > >>> "\spad{svd(m)} computes the singular value decomposition \spad{SVD} > of \spad{ > >>> m} such that \spad{SVD}.\spad{U} * diagonalMatrix(\spad{sv}) * > \spad{SVD}.\sp > >>> ad{Vt} = \spad{m}." > >>> "\spad{svd(m)} computes the singular value decomposition \spad{SVD} > of \spad{ > >>> m} such that \spad{SVD}.\spad{U} * diagonalMatrix(\spad{sv}) * > \spad{SVD}.\sp > >>> ad{Vt} = \spad{m}." > >>> "\spad{svd(m)} computes the singular value decomposition of the > matrix \spad{ > >>> m}." > >>> > Type: Void > >>> > >>> And regexing/replacing, completely irrelevant for me, some Tex-like > >>> construct I would like to obtain something like: > >>> (25) -> jlDocumentation "svd" > >>> > >>> "svd(m) computes the singular value decomposition SVD of m such that > >>> SVD.U * diagonalMatrix(sv) * SVD.Vt = m." > >>> "svd(m) computes the singular value decomposition SVD of m such that > >>> SVD.U * diagonalMatrix(sv) * SVD.Vt = m." > >>> "svd(m) computes the singular value decomposition SVD of m such that > >>> SVD.U * diagonalMatrix(sv) * SVD.Vt = m." > >>> "svd(m) computes the singular value decomposition SVD of m such that > >>> SVD.U * diagonalMatrix(sv) * SVD.Vt = m." > >>> "svd(m) computes the singular value decomposition of the matrix m." > >>> Type: > >>> Void > >>> > >>> or: > >>> > >>> (26) -> jlDocumentation "string" > >>> > >>> "string(f) gives string corresponding to f. Valid only when string?(f) > is true" > >>> "string(i) returns the decimal representation of i as a string." > >>> "string(s) returns s as an element of Str. Error: if s is not an atom > >>> that also belongs to Str." > >>> "string(jt) returns the string representation of jt." > >>> "string(x) stringifies x." > >>> "string(s) converts the symbol s to a string. Error: if the symbol is > >>> subscripted." > >>> > >>> (27) -> jlDocumentation "str" > >>> > Type: Void > >>> > >>> But with more information (conditional exports, origins etc.) and > >>> more options. Probably as a system command? > >>> )display doc string as an example. > >>> > >>> Just my two cents. > >>> > >>> - Greg > >>> > >>> -- > >>> You received this message because you are subscribed to a topic in the > Google Groups "FriCAS - computer algebra system" group. > >>> To unsubscribe from this topic, visit > https://groups.google.com/d/topic/fricas-devel/mb_O0196RMQ/unsubscribe. > >>> To unsubscribe from this group and all its topics, send an email to > fricas-devel...@googlegroups.com. > >>> To view this discussion visit > https://groups.google.com/d/msgid/fricas-devel/CAHnU2dY5SH52A0U56a8kSqSBO%2BFX0Lzsq%3Dw6hzBCfcuBd20m8Q%40mail.gmail.com > . > > > > -- > > You received this message because you are subscribed to the Google > Groups "FriCAS - computer algebra system" group. > > To unsubscribe from this group and stop receiving emails from it, send > an email to fricas-devel+unsubscr...@googlegroups.com. > > To view this discussion visit > https://groups.google.com/d/msgid/fricas-devel/d2b4d3a4-ce9e-4483-9d10-83f4add78e06n%40googlegroups.com > . > > -- > You received this message because you are subscribed to a topic in the > Google Groups "FriCAS - computer algebra system" group. > To unsubscribe from this topic, visit > https://groups.google.com/d/topic/fricas-devel/mb_O0196RMQ/unsubscribe. > To unsubscribe from this group and all its topics, send an email to > fricas-devel+unsubscr...@googlegroups.com. > To view this discussion visit > https://groups.google.com/d/msgid/fricas-devel/CAHnU2dYuiju2PAUO3GyADN1TXYBsaYE-MYKrUsCA-ZL9_g_4kg%40mail.gmail.com > . > -- You received this message because you are subscribed to the Google Groups "FriCAS - computer algebra system" group. To unsubscribe from this group and stop receiving emails from it, send an email to fricas-devel+unsubscr...@googlegroups.com. To view this discussion visit https://groups.google.com/d/msgid/fricas-devel/CAJn5L%3DKecxUfnoxp1sLEQOnY06s3RSrWejf2C%3DrzPCnZ%2BbdP7A%40mail.gmail.com.
