Broken references

[dbuenzli]

It seems some references are still broken. Examples:

1. The b0.b00.kit reference here (src) should link on that section (src)

2. In astring the old odoc, resolved these references fine. Nowdays they are unresolved.

[dbuenzli]

If that may help odig's log often shows absurd unambiguous resolutions e.g. here on opamFilename.odoc:

erratique> odig log --long --id 13405
[13405:spawn 47.6ms opam-core r:5a4719d95dc8e520]
 ['/home/erratique/tmp/odig/sample/_opam/bin/odoc' 'html' '--theme-uri'
  '_odoc-theme'
  '-o' '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamFilename.odoc'
  '-I' '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/'
  '-I' '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocamlgraph/'
  '-I' '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/'
  '-I' '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/re/']
 [0]
 File "set.mli", line 186, characters 16-27:
 Reference to 'Set' is ambiguous. Please specify its kind: module-Set, module-Set, module-Set.
 File "set.mli", line 201, characters 16-32:
 Reference to 'Set' is ambiguous. Please specify its kind: module-Set, module-Set, module-Set.
 File "set.mli", line 205, characters 16-36:
 Reference to 'Set' is ambiguous. Please specify its kind: module-Set, module-Set, module-Set.
 File "map.mli", line 219, characters 16-27:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map, module-Map.
 File "map.mli", line 238, characters 16-36:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map, module-Map.
 File "map.mli", line 244, characters 16-40:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map, module-Map.
 File "map.mli", line 326, characters 16-28:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map, module-Map.
 File "set.mli", line 186, characters 16-27:
 Reference to 'Set' is ambiguous. Please specify its kind: module-Set, module-Set.
 File "set.mli", line 201, characters 16-32:
 Reference to 'Set' is ambiguous. Please specify its kind: module-Set, module-Set.
 File "set.mli", line 205, characters 16-36:
 Reference to 'Set' is ambiguous. Please specify its kind: module-Set, module-Set.
 File "map.mli", line 219, characters 16-27:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map.
 File "map.mli", line 238, characters 16-36:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map.
 File "map.mli", line 244, characters 16-40:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map.
 File "map.mli", line 326, characters 16-28:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map.
 File "set.mli", line 186, characters 16-27:
 Reference to 'Set' is ambiguous. Please specify its kind: module-Set, module-Set.
 File "set.mli", line 201, characters 16-32:
 Reference to 'Set' is ambiguous. Please specify its kind: module-Set, module-Set.
 File "set.mli", line 205, characters 16-36:
 Reference to 'Set' is ambiguous. Please specify its kind: module-Set, module-Set.
 File "map.mli", line 219, characters 16-27:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map.
 File "map.mli", line 238, characters 16-36:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map.
 File "map.mli", line 244, characters 16-40:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map.
 File "map.mli", line 326, characters 16-28:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map.
 File "set.mli", line 186, characters 16-27:
 Reference to 'Set' is ambiguous. Please specify its kind: module-Set, module-Set, module-Set.
 File "set.mli", line 201, characters 16-32:
 Reference to 'Set' is ambiguous. Please specify its kind: module-Set, module-Set, module-Set.
 File "set.mli", line 205, characters 16-36:
 Reference to 'Set' is ambiguous. Please specify its kind: module-Set, module-Set, module-Set.
 File "map.mli", line 219, characters 16-27:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map, module-Map.
 File "map.mli", line 238, characters 16-36:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map, module-Map.
 File "map.mli", line 244, characters 16-40:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map, module-Map.
 File "map.mli", line 326, characters 16-28:
 Reference to 'Map' is ambiguous. Please specify its kind: module-Map, module-Map, module-Map.
 
 writes:
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Attribute/Map/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Attribute/Set/Op/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Attribute/Set/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Attribute/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Op/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Map/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Set/Op/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Set/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Dir/Map/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Dir/Set/Op/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Dir/Set/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Dir/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Base/Map/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Base/Set/Op/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Base/Set/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/Base/index.html'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/html/opam-core/OpamFilename/index.html'
 reads:
  '/home/erratique/tmp/odig/sample/_opam/bin/odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamFilename.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamFilename.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/page-index.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamVersionCompare.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamVersion.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamUrl.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamSystem.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamStubsTypes.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamStubs.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamStd.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamSHA.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamProcess.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamParallel.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamJson.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamHash.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamFilename.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamDirTrack.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamCoreConfig.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamConsole.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamCompat.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamCached.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamACL.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocamlgraph/graph__Sig.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/re/re__Cset.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/camlinternalLazy.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocamlgraph/graph.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/unix.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/stdlib__bytes.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/re/re__.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/stdlib__hashtbl.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/re/re__Category.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocamlgraph/graph__Oper.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/stdlib__buffer.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocamlgraph/graph__.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/stdlib__seq.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/re/re.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/stdlib__map.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocamlgraph/graph__Builder.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/stdlib__bigarray.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/stdlib.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/stdlib__lazy.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/re/re__Core.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/stdlib__uchar.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/stdlib__complex.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/re/re__Pmark.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/re/re__Automata.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/camlinternalFormatBasics.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/stdlib__set.odoc'
  '/home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/stdlib__format.odoc'
 success-exits: 0
 stdio: stdin <none> stderr <ui> stdout <ui>
 cwd: '/home/erratique/tmp/odig/sample/_opam/var/cache/odig'
 env: 
 stamps:
   env 
  args html --theme-uri _odoc-theme -o
   /home/erratique/tmp/odig/sample/_opam/var/cache/odig/html
   /home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/opamFilename.odoc
   -I /home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocaml/ -I
   /home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/ocamlgraph/ -I
   /home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/opam-core/ -I
   /home/erratique/tmp/odig/sample/_opam/var/cache/odig/odoc/re/
 timings: duration 47.6ms created 22s started 22s waited 37.4us

[jonludlam]

Thanks for the report! For the Astring issue, @Julow is still working on the suggestions in #478 (comment) - and I think this issue is related. The references in question are something like this:

(** Comment for module M, with reference: {!module-Foo} *)
module M : sig
  module Foo : sig end
end

so although the comment is written outside of module M, it must be resolved as if it was written inside.

[dbuenzli]

Right. Note that the .mld file error seem quite consistent, it seems to be all same page references. See the red links here:

https://b0-system.github.io/odig/doc/brr/index.html
https://b0-system.github.io/odig/doc/brr/ocaml_console.html

And compare to:

https://erratique.ch/software/brr/doc/
https://erratique.ch/software/brr/doc/ocaml_console.html

I redid a sample set https://b0-system.github.io/odig/doc/ with the current odig/odoc master. It's no longer maximal/best-effort since opam can no longer find a solution after a day. So its's a semi-random selection, I tried to put all the alternate stdlibs but core_kernel outs of memory (the server has only 1GB of memory and 0.5GB of swap) on html-targets of core_kernel.odoc.

[jonludlam]

Yep, that looks like a simple fix - #611

[jonludlam]

I believe this is fixed.

[dbuenzli]

I'm afraid this problem remains:

2. In astring the old odoc, resolved these references fine. Nowdays they are unresolved.

[dbuenzli]

I'm afraid this problem remains:

2. In astring the old odoc, resolved these references fine. Nowdays they are unresolved.

I think we basically agreed in #739 that this would not be solved. If your preamble comment is outside the module you have to prefix by the module to link inside.