In Axiom there is a documentation extension.
For each function there are the standard ++ documentation lines.
Since ++ is a comment we can "extend" the comment by appending a letter.
This is a method of providing "command line" documentation.
For example, in DeRhamComplex there is a function "leadingCoefficient"
The ++ documentation lines in the source code looks like:
leadingCoefficient : % -> R
++ leadingCoefficient(df) returns the leading
++ coefficient of differential form df.
++
++X der:=DERHAM(Integer,[x,y,z])
++X [dx,dy,dz]:=[generator(i)$der for i in 1..3]
++X f:BOP:=operator('f)
++X g:BOP:=operator('g)
++X h:BOP:=operator('h)
++X sigma:=f(x,y,z)*dx + g(x,y,z)*dy + h(x,y,z)*dz
++X leadingCoefficient sigma
Notice that in addition to the standard ++ comment lines there are ++X
comments
These provide command line examples of the use of the function.
So ")d op leadingCoefficient" shows the lines
der:=DERHAM(Integer,[x,y,z])
[dx,dy,dz]:=[generator(i)$der for i in 1..3]
f:BOP:=operator('f)
g:BOP:=operator('g)
h:BOP:=operator('h)
sigma:=f(x,y,z)*dx + g(x,y,z)*dy + h(x,y,z)*dz
leadingCoefficient sigma
These lines are not executed but show a user how to construct and use
a valid function call.
++X comments are easy to add to any function and can be specific to
any category, domain, or package function. They are just regular text
so they could include side-comments which would be part of the
)display output.
++X Note that this function is broken in certain ways, e.g.
++X foo(x) will fail if x is not ... etc.
Adding a scan-and-collect for ++X comments is trivial but greatly
enhances the command line help to give an example of function use.
On Tuesday, November 5, 2024 at 3:16:19 AM UTC-5 ra...@hemmecke.org wrote:
> On 11/5/24 08:12, Grégory Vanuxem wrote:
> > Try:
> > fricas -noht
> > compile the attached file and via the system command synonym )hd
> > browse for 'bar', you will see in boldface clickable examples.
>
> OK, that might be nice, but I am not interested in that. I am rather for
> removing HyperDoc altogether. So I'd rather like to see more ways that
> use current technology to browse the documentation.
>
> In fact, I consider ++ docstrings as not the right place for examples.
> Note, that they basically describe functions in the Category. For
> examples, however, one would have to be more concrete, i.e. choosing
> concrete values for the parameters. Also note that the documentation of
> a function like foo for DomainA, documents also foo from DomainB if we
> have something like
>
> Foo(X: Type): Category == with
> foo: (x, x) -> X
> DomainA(X: Type): Foo(X) == ...
> DomainB(X: Type, Y: Type): Foo(X) == ...
>
> The specification for foo might be easy, but for the examples, you
> cannot easily do them, because DomainA and/or DomainB have to be
> compiled in order to execute the examples for foo.
>
> I would actually go another way, namely providing notebooks for jfricas
> and showing them like here:
> https://fricas.github.io/fricas-notebooks/index.html
>
> As you see, a user can also download that notebook from Github.
>
> We simply need more people that write "executable" notebooks and commit
> to keeping them up-to-date with new versions of FriCAS.
>
> Ralf
>
--
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/424fc226-c9c0-46e7-a615-a0035f82e784n%40googlegroups.com.
