[bug#56576] [PATCH 1/2] gnu: Add stddoc.

[Maxime Devos <maximedevos@telenet.be>]

[-- Attachment #1.1.1: Type: text/plain, Size: 2364 bytes --]


On 07-08-2022 00:57, Antero Mejr via Guix-patches via wrote:
> +                              (invoke "gcc" "-O2" "-g" "-o" "stddoc" "stddoc.c")

For cross-compilation, you need to use #$(cc-for-target) instead of 
"gcc", otherwise it will be compiled for the wrong architecture.

> +                              (with-input-from-file "stddoc.c"
> +                                (lambda _
> +                                  (with-output-to-file "stddoc.c.html"
> +                                    (lambda _
> +                                      (invoke "./stddoc")))))))
Except when emulation is used, cross-compiled binaries cannot be run. 
However, you can add 'this-package' to native-inputs (conditional on 
cross-compilation, otherwise you get a loop) and run that stddoc:

(native-inputs (if (%current-target-system) (list this-package) '()))

[...]

(invoke #$(if (%current-target-system) "stddoc" "./stddoc"))

(untested!).

It includes Javascript and CSS from external sources:

> static void stddoc( FILE *in, FILE *out ) {
>     fprintf(out, "%s\n", "<meta charset='utf-8' emacsmode='-*- 
> markdown -*-'>");
>     fprintf(out, "%s\n", "<link rel='stylesheet' 
> href='https://casual-effects.com/m""arkdeep/latest/apidoc.css?'>");
>
I don't think this is good, privacy-wise, could you substitute them with 
a local copy?

Also, on 
<https://github.com/r-lyeh/stddoc.c/blob/6eef9deaf2e36bae812f50e448a8012b3e5efb14/stddoc.c#L111>, 
it looks like it forgets to quote things like &. I don't know if that's 
important in this particular case but often forgetting to quote things 
can be pretty bad.

(Ignoring the return value of printf also isn't ideal, but less important)

> +      (description "@code{stddoc.c} is a tiny documentation generator for 60
> +programming languages.  Markdeep code comments are extracted from stdin and
> +printed into stdout as a HTML file.")
This seems misleading to me, the Markdown->HTML happens at runtime, via 
the Javascript. Also, instead of mentioning the number 60, you could 
refer to the Javascript package; that way, the user can check if their 
language is in the list. I also don't think that the generator 
'https://morgan3d.github.io/markdeep/latest/markdeep.js' counts as tiny.

stdout -> output, stdin -> input

Greetings,
Maxime


[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 929 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 236 bytes --]