Documentation for own package

[Fabian Hassler]

I am reading the FriCAS book. I like it a lot as it provides a lot of useful information.

I am stuck with the Ch. 12.3, explaining how to include the documentation in the source code for the spad compiler. I am not sure but it feels that there is a way to produce a page in HyperDoc starting from the formalized way of including the comments. At least looking at the spad files in the algebra folder it looks like that.

How is this done in practice? I have found https://wiki.fricas.org/mathaction/FrontPage/HyperDoc which explains how to include the content of a .ht file. What I do not understand is how to produce a .ht file from the .spad source code. Is this possible?

P.S. Regarding the FriCAS book: in Listing 11.1 it seems that  "==>" corresponds to a macro definition. Is it the same as "macro". If yes, it would be useful to introduce the alternative notation in Ch. 6.2

[Ralf Hemmecke]

Dear Fabian.

Welcome to FriCAS!

On 1/22/25 09:20, Fabian Hassler wrote:
> I am stuck with the Ch. 12.3, explaining how to include the documentation
> in the source code for the spad compiler. I am not sure but it feels that
> there is a way to produce a page in HyperDoc starting from the formalized
> way of including the comments. At least looking at the spad files in the
> algebra folder it looks like that.

It is easier than you think, if you just need it in HyperDoc:
(1) start FriCAS (that by default also opens up an HyperDoc window.
(2) say ")compile YourProjectFILE.spad" (without quotes).
(3) goto the HyperDoc window and click on Browse
(4) search for one of your domains/categories etc.
(5) if you have any ++ docstrings in you code, you should see them.

If you want to produce a webpage from your package like this

https://hemmecke.github.io/qeta/

then look at the Makefiles in this package connected to doc and html. It
is basically the same as for the site http://fricas.github.io/ itself.

> P.S. Regarding the FriCAS book: in Listing 11.1 it seems that "==>"
> corresponds to a macro definition. Is it the same as "macro". If yes, it
> would be useful to introduce the alternative notation in Ch. 6.2

Yes,

foo ==> bar

is the same as

macro foo == bar

but is seems that the original authors of the book did not want to
promote ==> in the book. I actually never realized that ==> is not
explicitly introduced in the Book.

Ralf

[Fabian Hassler]

Thanks for the fast reply. I am far away of producing any package that is useful for somebody else ;-)

I have to say that the steps that you propose do not work for me. Do I have to be in any specific directory to make it work.

What I do: I am in some local folder (independent of the folder where fricas is installed). I have the following source:

--- content of quad.spad ---

)abbrev domain MYFORM MyQuadraticForm
++ Description:
++   This domain provides modest support for quadratic forms.
MyQuadraticForm(n, K) : T == Impl where
    n : PositiveInteger
    K : Field

    T ==> AbelianGroup with
        myQuadraticForm : SquareMatrix(n, K) -> %
            ++ \spad{myQuadraticForm(m)} creates a quadratic
            ++ form from a symmetric,
            ++ square matrix \spad{m}.
        matrix : % -> SquareMatrix(n, K)
            ++ \spad{matrix(qf)} creates a square matrix
            ++ from the quadratic form \spad{qf}.
        elt : (%, DirectProduct(n, K)) -> K
            ++ \spad{qf(v)} evaluates the quadratic form
            ++ \spad{qf} on the vector \spad{v},
            ++ producing a scalar.


    Impl ==> SquareMatrix(n, K) add
        Rep := SquareMatrix(n, K)

        myQuadraticForm m ==
            not symmetric? m => error
              "quadraticForm requires a symmetric matrix"
            m::%
        matrix q == q :: Rep
        elt(q, v) == dot(v, (matrix q * v))

I do start fricas from the command line (Hyperdoc opens in an xwindow). I do compile ")compile quad.spad". Then I search for myQuadraticForm or MyQuadraticForm but I do not find anything (even after closing and reopening of the window).

Fabian

[Ralf Hemmecke]

Dear Fabian,

I took you code into a file $HOME/mysquad/quad.spad, started fricas and then


(1) -> )compile quad.spad
Compiling FriCAS source code from file
/home/hemmecke/scratch/myquad/quad.spad using old system
compiler.
MYFORM abbreviates domain MyQuadraticForm
------------------------------------------------------------------------
initializing NRLIB MYFORM for MyQuadraticForm
compiling into NRLIB MYFORM
compiling exported myQuadraticForm : SquareMatrix(n,K) -> %
Time: 0.02 SEC.

compiling exported matrix : % -> SquareMatrix(n,K)
MYFORM;matrix;%Sm;2 is replaced by q
Time: 0 SEC.

compiling exported elt : (%,DirectProduct(n,K)) -> K
Time: 0 SEC.

(time taken in buildFunctor: 241)
Time: 0 SEC.


Cumulative Statistics for Constructor MyQuadraticForm
Time: 0.03 seconds

--------------non extending category----------------------
.. MyQuadraticForm(#1,#2) of cat
(|Join| (|AbelianGroup|)
(CATEGORY |domain|
(SIGNATURE |myQuadraticForm| (% (|SquareMatrix| |#1| |#2|)))
(SIGNATURE |matrix| ((|SquareMatrix| |#1| |#2|) %))
(SIGNATURE |elt| (|#2| % (|DirectProduct| |#1| |#2|))))) has no
(|SquareMatrixCategory| |#1| |#2| (|DirectProduct| |#1| |#2|)
(|DirectProduct| |#1| |#2|)) finalizing
NRLIB MYFORM
Processing MyQuadraticForm for Browser database:
--------constructor---------
--------(myQuadraticForm (% (SquareMatrix n K)))---------
--------(matrix ((SquareMatrix n K) %))---------
--------(elt (K % (DirectProduct n K)))---------
; compiling file "/home/hemmecke/scratch/myquad/MYFORM.NRLIB/MYFORM.lsp"
(written 22 JAN 2025 10:30:39 AM):

; file: /home/hemmecke/scratch/myquad/MYFORM.NRLIB/MYFORM.lsp
; in: SDEFUN |MYFORM;matrix;%Sm;2|
; (BOOT::SDEFUN BOOT::|MYFORM;matrix;%Sm;2|
; ((BOOT::|q| (BOOT::%))
; (BOOT::% (BOOT::|SquareMatrix| BOOT::|n| BOOT::K)))
; BOOT::|q|)
; --> PROGN SB-IMPL::%DEFUN SB-IMPL::%DEFUN SB-INT:NAMED-LAMBDA
; ==>
; #'(SB-INT:NAMED-LAMBDA BOOT::|MYFORM;matrix;%Sm;2|
; (BOOT::|q| BOOT::%)
; (BLOCK BOOT::|MYFORM;matrix;%Sm;2| BOOT::|q|))
;
; caught STYLE-WARNING:
; The variable % is defined but never used.
;
; compilation unit finished
; caught 1 STYLE-WARNING condition


; wrote /home/hemmecke/scratch/myquad/MYFORM.NRLIB/MYFORM.fasl
; compilation finished in 0:00:00.007
------------------------------------------------------------------------
MyQuadraticForm is now explicitly exposed in frame frame1
MyQuadraticForm will be automatically loaded when needed from
/home/hemmecke/scratch/myquad/MYFORM.NRLIB/MYFORM


===========

Now in the HyperDoc window I clicked Browse, entered MyQuadraticForm and
clicked on "constructors". The window then looks like in the attachment.

On 1/22/25 10:22, Fabian Hassler wrote:
> I have to say that the steps that you propose do not work for me. Do I have
> to be in any specific directory to make it work.

No.

> I do start fricas from the command line (Hyperdoc opens in an xwindow). I
> do compile ")compile quad.spad". Then I search for myQuadraticForm or
> MyQuadraticForm but I do not find anything (even after closing and
> reopening of the window).

Note that MyQuadraticForm will not be in HyperDoc after you leave fricas
and start fricas again. Entering your docstrings from quad.spad to
hyperdoc is done at compile-time and non-persistent.

Ralf

[Fabian Hassler]

Dear Ralf,

thanks for the clarification. If I do everything, as you describe. I get the same result! Thanks for the clarification.

Interestingly, I did almost everything as you explained. I just clicked on “General” instead of “Constructor”. So it seems that the documentation does not appear in the General section of HyperDoc (which is a bit confusing for me).

Best,
Fabian

> --
> 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/VAbiWPnrtoA/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/13137810-90f0-4a7b-9d91-daf97c04a258%40hemmecke.org.
> <Screenshot_2025-01-22_10-31-32.png>

[Waldek Hebisch]

On Wed, Jan 22, 2025 at 01:20:41AM -0800, Fabian Hassler wrote:
> Thanks for the fast reply. I am far away of producing any package that is
> useful for somebody else ;-)
>

> I have to say that the steps that you propose do not work for me. Do I have
> to be in any specific directory to make it work.
>

> What I do: I am in some local folder (independent of the folder where
> fricas is installed). I have the following source:
>
> --- content of quad.spad ---

<snip>

> I do start fricas from the command line (Hyperdoc opens in an xwindow). I
> do compile ")compile quad.spad". Then I search for myQuadraticForm or
> MyQuadraticForm but I do not find anything (even after closing and
> reopening of the window).

Which version are you using?

I wrote code that you provided to file 'quad.spad'. Then using
developement version of FriCAS, at FriCAS prompt I did:

)compile quad.spad

which produced several messages including the following block:

Processing MyQuadraticForm for Browser database:
--------constructor---------
--------(myQuadraticForm (% (SquareMatrix n K)))---------
--------(matrix ((SquareMatrix n K) %))---------
--------(elt (K % (DirectProduct n K)))---------

Ater that, in the same FriCAS session, HyperDoc search for
constructors found MyQuadraticForm and HyperDoc search for
operations found myQuadraticForm.

If I restart FriCAS, then it forgets about new domain. One
can do

)boot $createLocalLibDb := true

This causes FriCAS to write information obout new operations
to a file which is automatically read when you restart
FriCAS in the same dorectory. To see info about constructor
(and to be able to use it), do

)lib MYFORM

after restarting FriCAS.

When I tried fricas-1.3.11 (that is latest release) after
compiling I was able to see info about constructior but
info about operations was missing. However, after setting
'$createLocalLibDb' to true (like above) info about new
operation showed up.

--
Waldek Hebisch

[Fabian Hassler]

I am using:

"FriCAS 1.3.11 built with sbcl 2.5.0”

Searching for the name “MyQuadraticForm” in the “Constructor" section does work. However, searching for it in the “General” section does not work. Moreover, searching with the wildcard “MyQuadratic*” also does not work.

If I use the trick: ')boot $createLocalLibDb := true'

then suddenly the general tab, as well as the wildcard search work.

Fabian

> --
> 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/VAbiWPnrtoA/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/Z5DT08oGgkHPviwJ%40fricas.org.