affeldt-aist / coq2html Goto Github PK

@yoshihiro503

@proux01 : let's think of a test suite to check the stability of coq2html and put in the CI
(MathComp-Analysis dev meeting [2024-02-09])

when using coq2html against contra.v I noticed the following inconsistent behavior: |2 is turned into a link only two one place but maybe it shouldn't be

• very minor: in #[short(type=semiRingOfSetsType)], an extra spurious space is introduced after short
  @proux01

very minor: some links to stdlib notations are partly broken (for instance https://coq.inria.fr/doc/V8.18.0/stdlib/Coq.Init.Specif.html#::type_scope:'{'_x_':'_x_'|'_x_'&'_x_'}' or https://coq.inria.fr/doc/V8.18.0/stdlib/Coq.ssr.ssrfun.html#::fun_scope:x_'=1'_x )
@proux01

It looks like compilation with OCaml version 4.11.2 errors:

ocamlopt -c coq2html.ml
File "coq2html.mll", line 291, characters 5-13:
Error: Unbound value Seq.find
make: *** [Makefile:10: coq2html.cmx] Error 2

There is maybe a minimal version for OCaml to require in the README. @yoshihiro503

not sure why HB.mixin and some HB.instance get displayed in red but not all HB.structure (I would either display nothing in red or all of the commands in https://github.com/math-comp/hierarchy-builder/blob/master/structures.v with some link to that file in addition to the color
@proux01

for example, in the parameters of filter_prod in https://yoshihiro503.github.io/coq2html/mathcomp.analysis.topology.html
spaces have been added after the opening parenthesis and the variable F
there are several such spurious spaces here and there

minor: some internal links seem broken: https://yoshihiro503.github.io/coq2html/mathcomp.classical.mathcomp_extra.html#P:4 works great but https://yoshihiro503.github.io/coq2html/mathcomp.classical.mathcomp_extra.html#T:2 doesn't
@proux01

"very minor: HTML title of that page: "Module $NAME"" @proux01

One could claim that scripts ought to start with Proof
but what about when this is a tactic-based definition this?

see https://yoshihiro503.github.io/coq2html/monae/monae.example_typed_store.html for example

@garrigue

"are th three stars before md mandatory? why not just two? (coqdoc syntax is (** IIRC so not sure a third star is needed)"

"in case we wouldn't use block comments, with stars all around, but just start (* and closing *) syntax, the less stars the better I'd say."

@proux01

I get the following warnings when compiling:

File "generate_index.ml", lines 219-231, characters 17-38:
Warning 8 [partial-match]: this pattern-matching is not exhaustive.
Here is an example of a case that is not matched:
[]::_
File "coq2html.mll", line 390, characters 39-40:
Warning 26 [unused-var]: unused variable s.
File "coq2html.mll", line 397, characters 63-64:
Warning 26 [unused-var]: unused variable s.
File "coq2html.mll", line 403, characters 64-65:
Warning 26 [unused-var]: unused variable s.
File "coq2html.mll", line 535, characters 34-35:
Warning 26 [unused-var]: unused variable s.

those probably need to be addressed.

the table of content generated from the first title of each file, following the order of the _CoqProject
(coqdoc feature not in coq2html)
@proux01

serious: links to section variables can be broken, for instance https://yoshihiro503.github.io/coq2html/mathcomp.analysis.measure.html#classes.G
@proux01

serious: some links to HB defined types are broken, for instance https://yoshihiro503.github.io/coq2html/mathcomp.analysis.measure.html#ringOfSetsType

@proux01

"This made me discover that coq2html is basically just removing the initial (* and trailing *) but keeps all the trailing whitespaces. I'm not sure we want this since two whitespaces, or more, have a specific semantics in markdown (force line break). This may lead to strange results, depending on the number of space before the final *) (which is something we don't control and which shouldn't have any meaning)." @proux01

• minor but probably easy to fix: missing purple keywords
  • Set Implicit Arguments.
  • Unset Strict Implicit
  • Unset Printing Implicit Defensive
  • Number Notation
  • Declare Scope
  • Delimit Scope
  • Bind Scope
  • Local
    @proux01

See for example this output:

The behavior should be consistent, if the headers stick to, e.g., an 80 column limit, then you might have some line ending on last words *) and another line ending in last words *), producing two different line break behaviors.

If it's unsupported yet then it should be documented, otherwise this looks like a simple fix.

I get the following error:

ocamlopt -c generate_index.mli
(for i in header footer css js redirect; do \
         echo "let $i = {xxx|"; \
         cat coq2html.$i; \
         echo '|xxx}'; \
         done) > resources.ml
ocamlopt -c resources.ml
ocamlopt -c generate_index.ml
File "_none_", line 1:
Alert ocaml_deprecated_auto_include: 
OCaml's lib directory layout changed in 5.0. The str subdirectory has been
automatically added to the search path, but you should add -I +str to the
command-line to silence this alert (e.g. by adding str to the list of
libraries in your dune file, or adding use_str to your _tags file for
ocamlbuild, or using -package str for ocamlfind).

File "generate_index.ml", line 167, characters 19-28:
167 |   String.(compare (lowercase s1) (lowercase s2))
                         ^^^^^^^^^
Error: Unbound value lowercase
make: *** [Makefile:10: generate_index.cmx] Error 2

I'm testing this on my repository, I'll be happy to report my experience

For example, in the following code, the second -> is not correctly linked.

Definition ty := (bool -> nat) -> unit.

This is because the location of the glob file starts two places off from the actual -> location and points to the ) -> part.

R29:33 Coq.Init.Logic <> ::type_scope:x_'->'_x not

very minor: some links to mathcomp seem broken: https://math-comp.github.io/htmldoc/mathcomp.algebra.ssralg.html#GRing.Zmodule.Exports.zmodType
(looks like it's not a coq2html bug but the fact that doc of Analysis master (still on MC1) should link to the doc of MC1 not MC master (MC2))

@proux01

This is more like a wish, for you to publish binary releases for Linux that can be used in GitHub workflows.
Having a pre-release versions published would allow to test and produce valid workflow documentation

• the ability to easily link to constants in the comments (by just surrounding them with [ and ]
  (coqdoc feature not in coq2html)
  @proux01