Re: [fricas/fricas] Unsupported keyword: verb (in HyperDoc) (Issue #185)

[Grégory Vanuxem]

Displays nicely for me. I also use backslash, empirically found, to
quickly create Mathematica lists in \example{}.
From what I have seen \verb is only used here and other uses are for
"literate" sections.

- Greg

Le mar. 22 oct. 2024 à 06:37, Qian Yun <notifi...@github.com> a écrit :
>
> The intention of \verb is to print \[ and \] verbatimly.
>
> In https://github.com/fricas/fricas/blob/c39b7dea46db0cd3635205cb36378d4da31296af/src/doc/ht/HTXFormatPage1.ht#L5-L6
>
> it says we can simply use the backslash char to escape.
>
> So the following patch will fix this issue.
>
> diff --git a/src/algebra/tex.spad b/src/algebra/tex.spad
> index 5083875f..13d34596 100644
> --- a/src/algebra/tex.spad
> +++ b/src/algebra/tex.spad
> @@ -18,7 +18,7 @@
> ++ The other parts can be set (\spadfun{setPrologue!},
> ++ \spadfun{setEpilogue!}) so that contain the appropriate tags for
> ++ printing. For example, the prologue and epilogue might simply
> -++ contain ``\verb+\[+'' and ``\verb+\]+'', respectively, so that
> +++ contain ``\\\['' and ``\\\]'', respectively, so that
> ++ the TeX section will be printed in LaTeX display math mode.
>
> TexFormat() : public == private where
>
> —
> Reply to this email directly, view it on GitHub, or unsubscribe.
> You are receiving this because you authored the thread.Message ID: <fricas/fricas/issues/185/24282...@github.com>

[Grégory Vanuxem]

(from GitHub issues)

Hello Ralf, and others,

Le dim. 3 nov. 2024 à 00:52, Ralf Hemmecke <notifi...@github.com> a écrit :

The ++ docstrings have absolutely nothing to do with the book.
They are, however, massaged in order to give "reasonable" output when processed by sphinx-doc.
I have the impression that the docstrings do not always use proper hypertex.
Some day we should agree on a better format, for example, MarkDown or reStructuredText. That would be reasonably readable (better than HyperTex) and there are converters to translate that to other formats like html or pdf. As long as we can produce the HyperTex format from it to keep HyperDoc happy, that would be a tedious work but can be done gradually.

I completely agree. Something that pandoc[1] or others can handle, it's just an example I am not a specialist. Furthermore we have your FriCAS Web API generator (src/doc/api.spad) that could help a lot I think. By the way, do you know if reStrucuredText handles examples? \example{} in HyperTex? Or, maybe you know where I have to look?

Greg

[1] https://pandoc.org/

—

Reply to this email directly, view it on GitHub, or unsubscribe.

You are receiving this because you authored the thread.Message ID: <fricas/fricas/issues/185/2453228771@github.com>

[Ralf Hemmecke]

Hi Greg,

On 11/4/24 18:30, Grégory Vanuxem wrote:
> By the way, do you know if reStrucuredText handles examples?
> \example{} in HyperTex? Or, maybe you know where I have to look?

No, certainly not. You must understand, that the ++ docstrings basically
have to be written in HyperTex (even for that I am not completely sure).
Anyway how exactly they are translated for theyr appearance in HyperDoc,
I have not taken the effort to look up (yet), but all of that is
certainly in some source code in FriCAS. It is just that HyperTex is
nowadays not a "common" format anymore as reStructuredText or MarkDown is.

I guess, one would have to rewrite \examples{}, but I guess, we could
learn from the Sage people and just "invent" a certain format that
allows code in the ++ docstrings that would be executed when the
generation of the api website happens. I think sphinx-doc allows quite
some flexibility, but without agreeing on a particular format
(reStructuredText or MarkDown) it makes no sense to look deeper into it.

Ralf

[Grégory Vanuxem]

That’s interesting, I will look at how SAGE folks manage this, thanks.

In fact, as of now, my primary concern is formatting examples in a "not" ugly way. Furthermore, I am not at a stage where \example{}s are clickable and executed in an Xterm like HyperDoc do, just api.spad does not seem to handle them. I also do not know how HyperTex processes their commands, and even more, when I wrote multiline examples I wrote several \example{} lines. HyperDoc handles this, this why I do this that way. Maybe I can test other ways.

By the way, improving how FriCAS handles ++ documentation is a must do for me.

Greg

--
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...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/fricas-devel/4cb8b36b-6dd2-49ae-affd-a432805eaada%40hemmecke.org.

[Ralf Hemmecke]

On 11/4/24 22:18, Grégory Vanuxem wrote:
> In fact, as of now, my primary concern is formatting examples in a "not"
> ugly way. Furthermore, I am not at a stage where \example{}s are clickable
> and executed in an Xterm like HyperDoc do, just api.spad does not seem to
> handle them.

Exactly. I was already wondering, but now grep'ed for \example. In fact,
\example does not appear inside ++ docstrings. So why should api.spad
handle that?

> I also do not know how HyperTex processes their commands, and
> even more, when I wrote multiline examples I wrote several \example{}
> lines. HyperDoc handles this, this why I do this that way. Maybe I can test
> other ways.

Let me first clarify the concepts.

"HyperTex" is a format. It probably comes from HyperText an invention at
a time where HTML was not yet there. And since TeX was well known the
authors modeled a HyperText format in a TeX-like fashion.

"HyperDoc" is the program that presents HyperTeX documents to the user.

In modern terms HyperTex ist HTML and HyperDoc is a browser.

You find a lot of *.ht files in the sources. That is HyperTex format.
The .htex files are a mixture of LaTeX and HyperTex. Before they can be
shown in HyperDoc, they are translated into .ht files. This is done by
src/doc/ht.awk.

How ++ docstrings are handled for HyperDoc, I have not looked at since I
was only interested in translating them into what we now have at
fricas.github.io/api. I basically tried to translate the ++ docstrings
into an .rst format and let sphinx-doc do the rest.

> By the way, improving how FriCAS handles ++ documentation is a must do for
> me.

What exactly do you want? Do you insist on using HyperDoc or do you
prefer a web version (HTML)?

Ralf

[Grégory Vanuxem]

Hi,

Le lun. 4 nov. 2024 à 22:57, 'Ralf Hemmecke' via FriCAS - computer

algebra system <fricas...@googlegroups.com> a écrit :
>

> On 11/4/24 22:18, Grégory Vanuxem wrote:
> > In fact, as of now, my primary concern is formatting examples in a "not"
> > ugly way. Furthermore, I am not at a stage where \example{}s are clickable
> > and executed in an Xterm like HyperDoc do, just api.spad does not seem to
> > handle them.
>
> Exactly. I was already wondering, but now grep'ed for \example. In fact,
> \example does not appear inside ++ docstrings. So why should api.spad
> handle that?

Try:
fricas -noht
compile the attached file and via the system command synonym )hd
browse for 'bar', you will see in boldface clickable examples.
I no longer remember how I found this HyperTex command but I found it
interesting since as I said before FriCAS really lacks examples for
numerous routines defined in Spad. I know there is a book, but that's
different and having clickable examples or even more, in HTML, a copy
link like the ones in the upper right corner in a lot of other
projects for their documentation actually, that's really a plus.

>
> > I also do not know how HyperTex processes their commands, and
> > even more, when I wrote multiline examples I wrote several \example{}
> > lines. HyperDoc handles this, this why I do this that way. Maybe I can test
> > other ways.
>
> Let me first clarify the concepts.
>
> "HyperTex" is a format. It probably comes from HyperText an invention at
> a time where HTML was not yet there. And since TeX was well known the
> authors modeled a HyperText format in a TeX-like fashion.
>
> "HyperDoc" is the program that presents HyperTeX documents to the user.
>
> In modern terms HyperTex ist HTML and HyperDoc is a browser.
>
> You find a lot of *.ht files in the sources. That is HyperTex format.
> The .htex files are a mixture of LaTeX and HyperTex. Before they can be
> shown in HyperDoc, they are translated into .ht files. This is done by
> src/doc/ht.awk.

Ok

>
> How ++ docstrings are handled for HyperDoc, I have not looked at since I
> was only interested in translating them into what we now have at
> fricas.github.io/api. I basically tried to translate the ++ docstrings
> into an .rst format and let sphinx-doc do the rest.
>
> > By the way, improving how FriCAS handles ++ documentation is a must do for
> > me.
>
> What exactly do you want? Do you insist on using HyperDoc or do you
> prefer a web version (HTML)?

The two for now, as you suggested previously/ since rst or md files
can be easily converted apparently, but, yes, a format needs to be
chosen or we need to "jungle" between different formats, a waste of
time for me.

Greg

[Ralf Hemmecke]

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

[Tim Daly]

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.

[Waldek Hebisch]

On Mon, Nov 04, 2024 at 10:18:41PM +0100, Grégory Vanuxem wrote:
> That’s interesting, I will look at how SAGE folks manage this, thanks.
>
> In fact, as of now, my primary concern is formatting examples in a "not"
> ugly way. Furthermore, I am not at a stage where \example{}s are clickable
> and executed in an Xterm like HyperDoc do, just api.spad does not seem to
> handle them. I also do not know how HyperTex processes their commands,

That is all documented in chapter about writing HyperDoc pages.
There is small number of base constructs understood by HyperDoc:

- \lisplink
- \windowlink
- \spadcommand
- \unixommand

with some variants + bunch of formatting constructs. HyperDoc has
macros and the rest expands to those above. In particular '\example'
expands to '\spadcommand' with some added formatting.

During normal operation HyperDoc is connected to FriCAS and may
request computations, '\lisplink' and '\spadcommand' send expression
which is evaluated as Lisp or FriCAS input expression respectively.
Some HyperDoc features are realized by dedicated functions written in
Boot, in particular browser is done in this way. More precisely,
HyperTex macro expand to a command which sends Lisp code to FRICASsys.
FRICASsys evaluates Lisp code which generates page content which is
then rendered by HyperDoc. Currently this depends on Lisp and Boot.
But with small changes this code could be written in Spad. In
particular in my private version, part of this is done by Spad code.
Commands are still sent as Lisp commands (to avoid large changes in
other parts) and actual content is still generated by Boot code (it
needs much more work before all this is handled by Spad), but page
data is gathered in Spad data structures and actual sending of data
from FRICASsys to HyperDoc is done by Spad code.

--
Waldek Hebisch

[Grégory Vanuxem]

Looking previous mails, that's very interesting, thanks.

(forgotten mail).

- Greg