File used by hyperdoc(?) for functions documentation

[Grégory Vanuxem]

Hello all,

In the past I wrote code to access from the interpreter to the ++
documentation of each function if documentation is available.

The problem is, first the SDD which contains the code is one of the
first SDD sent on a laptop (broken laptop) and finding an adaptor to
read it is "la croix et la bannière". But, It seems to me that there
is a file that contains the documentation of the functions after the
build, eventually for HyperDoc I do not remember.

Does it exist and if yes, which one maybe?

Regards,

- Greg

[Waldek Hebisch]

On Thu, Feb 06, 2025 at 03:59:51PM +0100, Grégory Vanuxem wrote:
> Hello all,
>
> In the past I wrote code to access from the interpreter to the ++
> documentation of each function if documentation is available.

Did you use IndexCard?

--
Waldek Hebisch

[Grégory Vanuxem]

No, I do not know this domain in fact, I will look into it. But, since
with Julia I added StyledStrings and I already support Regex (official
modules) I wanted to see if I can produce "styled" documentation in
the interpreter from the ++ documentation eventually with color, bold
font, italic etc. IndexCard has ++documentation access???

- Greg

PS / https://julialang.github.io/StyledStrings.jl/dev/examples/

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

[Grégory Vanuxem]

Is IndexCard buggy or am I using it wrongly?

(3) -> "string".doc

>> System error:
The bounding indices 7 and 6 are bad for a sequence of length 6.
See also:
The ANSI Standard, Glossary entry for "bounding index designator"
The ANSI Standard, writeup for Issue SUBSEQ-OUT-OF-BOUNDS:IS-AN-ERROR

Maybe you have an example of its use in mind?

[Waldek Hebisch]

On Thu, Feb 06, 2025 at 05:59:54PM +0100, Grégory Vanuxem wrote:
> Is IndexCard buggy or am I using it wrongly?
>
> (3) -> "string".doc
>
> >> System error:
> The bounding indices 7 and 6 are bad for a sequence of length 6.
> See also:
> The ANSI Standard, Glossary entry for "bounding index designator"
> The ANSI Standard, writeup for Issue SUBSEQ-OUT-OF-BOUNDS:IS-AN-ERROR

The above first coerces "string" to IndexCard and then tries to use
it. From documentation of IndexCard:

coerce : String -> %
++ coerce(s) converts \spad{s} into an \spad{IndexCard}. Warning: if
++ \spad{s} is not of the right format then an error will occur when using
++ it.

AFAICS "the right format" means internal format of documentation
strings. "string" certainly is not of this format.

> Maybe you have an example of its use in mind?

The following works for me:

os := getDatabase("o")
str := os.(name="string")
elt(str, doc)

--
Waldek Hebisch

[Waldek Hebisch]

On Thu, Feb 06, 2025 at 05:34:52PM +0100, Grégory Vanuxem wrote:
> No, I do not know this domain in fact, I will look into it.

Maybe you used a Boot function. For example you could look at
implementation of IndexCard or maybe 'api.spad' by Ralf (I do not
remember if Ralf uses IndexCard but probably he calls Boot).
Depending on your needs you may decide to use 'api.spad', domains
there are doing more than IndexCard.

> But, since
> with Julia I added StyledStrings and I already support Regex (official
> modules) I wanted to see if I can produce "styled" documentation in
> the interpreter from the ++ documentation eventually with color, bold
> font, italic etc. IndexCard has ++documentation access???

Have you looked at what Krystian Bacławski did? His repo is:

https://github.com/cahirwpz/phd

His goal was Spad type checker, but as part of infrastructure he
implemented colored messages.

Also, regexes are rather inconvenient if you need parsing. As
part of api2.spad:

http://wiki.fricas.org/public/api2.spad

I created domains TeXScanner and TeXTree which implement LaTeX
parser capable of handling all docsting in the trunk. Currently
the parser is quite picky and signals errors for unknown control
sequences, but that could be easily changed. For example it could
ignore unknown control sequences, so that you would just get arguments.

--
Waldek Hebisch

[Grégory Vanuxem]

Hello Waldek, *,

Le jeu. 6 févr. 2025 à 19:40, Waldek Hebisch <de...@fricas.org> a écrit :
>
> On Thu, Feb 06, 2025 at 05:34:52PM +0100, Grégory Vanuxem wrote:
> > No, I do not know this domain in fact, I will look into it.
>
> Maybe you used a Boot function. For example you could look at
> implementation of IndexCard or maybe 'api.spad' by Ralf (I do not
> remember if Ralf uses IndexCard but probably he calls Boot).
> Depending on your needs you may decide to use 'api.spad', domains
> there are doing more than IndexCard.
>
> > But, since
> > with Julia I added StyledStrings and I already support Regex (official
> > modules) I wanted to see if I can produce "styled" documentation in
> > the interpreter from the ++ documentation eventually with color, bold
> > font, italic etc. IndexCard has ++documentation access???
>
> Have you looked at what Krystian Bacławski did? His repo is:
>
> https://github.com/cahirwpz/phd

What an apparent interesting work! I thought it was a Google SoC but no
in fact, it's a PhD work.

>
> His goal was Spad type checker, but as part of infrastructure he
> implemented colored messages.
>
> Also, regexes are rather inconvenient if you need parsing.

Yes I know but from memory there was a file, difficult to parse from
memory, but I am pretty sure it existed.

> As
> part of api2.spad:
>
> http://wiki.fricas.org/public/api2.spad

Thanks for the URL remainder!

>
> I created domains TeXScanner and TeXTree which implement LaTeX
> parser capable of handling all docsting in the trunk. Currently
> the parser is quite picky and signals errors for unknown control
> sequences, but that could be easily changed. For example it could
> ignore unknown control sequences, so that you would just get arguments.

Not really read as of now this file + the one from Ralf. Same
for the protocol to communicate with HyperDoc, I need to goodly
interface a terminal with FriCAS, I can easily use tmux but for sure
I am not at all a big fan of tmux. I think I will look into those
domains, I know, regexing is not THE solution + it depends on an alien
component.

In any case, thank you for this good information!


Have a good day!

- Greg

>
> --
> Waldek Hebisch
>
> --
> 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/Z6UCHtnjXEknlBqT%40fricas.org.

[Grégory Vanuxem]

Your Spad example is exactly what I was will looking for. Yes!! And looking at the code  was very easy to understand now!

In fact I would like a system command with example when they are available à la Julia. Or something else like that, that doesn't matter. And in Spad almost all I want is there, I didn't know. I love also the fullDisplay from you beginning example, but more is in:

(15) -> fullDisplay str
        fullDisplay str
   string : (OutputForm)->String from OutputFormTools (unexposed)
   string : (Integer)->% from StringCategory
   string : (%)->Str from SExpressionCategory(Str,Sym,Int,Flt)
   string : (%)->String from JLObjectType
   string : (%)->String from JLType
   string : (%)->String from JLInt64
   string : (%)->String from Symbol

This is not the documentation here but I also need where the doc come from, domains, categories, packages. In FriCAS with Julia support I have for example:

(16) -> )jlApropos svd
        )jlApropos svd
LinearAlgebra.svdvals
LinearAlgebra.svd!
LinearAlgebra.GeneralizedSVD
LinearAlgebra.svdvals!
LinearAlgebra.rank
LinearAlgebra.svd
LinearAlgebra.SVD
LinearAlgebra.LAPACK.ggsvd!
LinearAlgebra.LAPACK.gesvd!
LinearAlgebra.LAPACK.ggsvd3!
LinearAlgebra.LAPACK.gelsd!

There is also in FriCAS (the orthographic corrector is only there because I cut and paste the interpreter output in a themed editor but colored name are in the interpreter):

(16) -> )jlDoc svd

        )jlDoc svd

  svd(A; full::Bool = false, alg::Algorithm = default_svd_alg(A)) -> SVD

  Compute the singular value decomposition (SVD) of A and return an SVD

  object.

  U, S, V and Vt can be obtained from the factorization F with F.U, F.S, F.V

  and F.Vt, such that A = U * Diagonal(S) * Vt. The algorithm produces Vt and

  hence Vt is more efficient to extract than V. The singular values in S are

  sorted in descending order.

  Iterating the decomposition produces the components U, S, and V.

  If full = false (default), a "thin" SVD is returned. For an M \times N

  matrix A, in the full factorization U is M \times M and V is N \times N,

  while in the thin factorization U is M \times K and V is N \times K, where K

  = \min(M,N) is the number of singular values.

  If alg = DivideAndConquer() a divide-and-conquer algorithm is used to

  calculate the SVD. Another (typically slower but more accurate) option is

  alg = QRIteration().

  │ Julia 1.3

  │

  │  The alg keyword argument requires Julia 1.3 or later.

  Examples

  ≡≡≡≡≡≡≡≡

  julia> A = rand(4,3);

  julia> F = svd(A); # Store the Factorization Object

  julia> A ≈ F.U * Diagonal(F.S) * F.Vt

  true

  julia> U, S, V = F; # destructuring via iteration

  julia> A ≈ U * Diagonal(S) * V'

  true

  julia> Uonly, = svd(A); # Store U only

  julia> Uonly == U

  true

  svd(A, B) -> GeneralizedSVD

  Compute the generalized SVD of A and B, returning a GeneralizedSVD

  factorization object F such that [A;B] = [F.U * F.D1; F.V * F.D2] * F.R0 *

  F.Q'

    •  U is a M-by-M orthogonal matrix,

    •  V is a P-by-P orthogonal matrix,

    •  Q is a N-by-N orthogonal matrix,

    •  D1 is a M-by-(K+L) diagonal matrix with 1s in the first K entries,

    •  D2 is a P-by-(K+L) matrix whose top right L-by-L block is

       diagonal,

    •  R0 is a (K+L)-by-N matrix whose rightmost (K+L)-by-(K+L) block is

       nonsingular upper block triangular,

  K+L is the effective numerical rank of the matrix [A; B].

  Iterating the decomposition produces the components U, V, Q, D1, D2, and R0.

  The generalized SVD is used in applications such as when one wants to

  compare how much belongs to A vs. how much belongs to B, as in human vs

  yeast genome, or signal vs noise, or between clusters vs within clusters.

  (See Edelman and Wang for discussion: https://arxiv.org/abs/1901.00485)

  It decomposes [A; B] into [UC; VS]H, where [UC; VS] is a natural orthogonal

  basis for the column space of [A; B], and H = RQ' is a natural

  non-orthogonal basis for the rowspace of [A;B], where the top rows are most

  closely attributed to the A matrix, and the bottom to the B matrix. The

  multi-cosine/sine matrices C and S provide a multi-measure of how much A vs

  how much B, and U and V provide directions in which these are measured.

  Examples

  ≡≡≡≡≡≡≡≡

  julia> A = randn(3,2); B=randn(4,2);

  julia> F = svd(A, B);

  julia> U,V,Q,C,S,R = F;

  julia> H = R*Q';

  julia> [A; B] ≈ [U*C; V*S]*H

  true

  julia> [A; B] ≈ [F.U*F.D1; F.V*F.D2]*F.R0*F.Q'

  true

  julia> Uonly, = svd(A,B);

  julia> U == Uonly

  true

- Greg