Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ocamldoc isn't creating all the manual pages in 4.02/3 #6425

Closed
vicuna opened this issue May 16, 2014 · 5 comments
Closed

ocamldoc isn't creating all the manual pages in 4.02/3 #6425

vicuna opened this issue May 16, 2014 · 5 comments

Comments

@vicuna
Copy link

vicuna commented May 16, 2014

Original bug ID: 6425
Reporter: @avsm
Assigned to: @zoggy
Status: closed (set by @zoggy on 2014-09-08T13:12:45Z)
Resolution: fixed
Priority: normal
Severity: major
Target version: 4.02.0+dev
Category: ocamldoc
Monitored by: @hcarty

Bug description

After making ocamldoc/stdlib_man, some pages (such as Format.3o) are now missing. They were built previously in 4.01, and the corresponding HTML pages in stdlib_html are still present. This points to an issue in the ocamldoc man page backend.

Steps to reproduce

Do a build and (results below from Gabriel)

$ ls -1 stdlib_html/* | grep "/[A-Z][a-zA-Z_].html" | grep "/[A-Z][a-zA-Z_]." -o | sort > /tmp/dochtml
$ ls -1 stdlib_man/* | grep "/[A-Z][a-zA-Z_].3o" | grep "/[A-Z][a-zA-Z_]." -o | sort > /tmp/docman
$ diff /tmp/doc{html,man}
13d12
< /Char.
17d15
< /Format.
21d18
< /Lazy.
28d24
< /Nativeint.
39d34
< /Set.
45d39
< /String.

@vicuna
Copy link
Author

vicuna commented May 16, 2014

Comment author: @gasche

I bisected this to a surprising result: the faulty change is my own commit
"Use a nominal datatype for CamlinternalFormat.format6"
It seems to breaks manpage generation under either trunk or 4.02 -- while totally unrelated.

Investigating.

@vicuna
Copy link
Author

vicuna commented May 16, 2014

Comment author: @damiendoligez

This is an ocamldoc bug triggered by the option -man-mini:

   -man-mini
          Generate  man  pages only for modules, module types, classes and
          class types, instead of pages for all elements.

What all these modules have in common, is that there are data constructors of the same names in other modules. When I remove the constructors from the type declarations in their respective .mli files, the man pages of these modules are output as expected.

I have not looked at the ocamldoc code so I've no idea how to fix it, but this one is clearly for Maxence.

@vicuna
Copy link
Author

vicuna commented May 22, 2014

Comment author: @zoggy

I'm looking at this.

@vicuna
Copy link
Author

vicuna commented May 22, 2014

Comment author: @zoggy

When the -man-mini is not given, ocamldoc generates a .3o file for each value,type,..., name. This file lists the occurrences of this name and the module it belongs to. For example, iter.3o will list Bytes.iter, Array.iter, ...

Of course, when a variant constructor has the same name as a module, both should be listed in a common file, for example Format.3o. But with the -man-mini option, only files corresponding to one class [type] or one module [type] are created, hence the missing files. I say "should" because in fact record fields, variant constructors and modules are not listed in such .3o files. (for example, the Format.3o file generated without -man-mini option does not list any elements). I'll add some code to list them, hoping the resulting man page will not be too unpleasant to read.

Another, simpler, solution is to "forget" variant constructors, preventing conflict with module names.

@vicuna
Copy link
Author

vicuna commented May 22, 2014

Comment author: @zoggy

Fixed in revisions 14901(version/4.02) and 14902(trunk).
When the -man-mini option is passed, only classes, class types, modules and module types are kept to generate .3o files. The previous filter preventing the generation of .3o files containing more than one element is removed.

@vicuna vicuna closed this as completed Sep 8, 2014
@vicuna vicuna added this to the 4.02.0 milestone Mar 14, 2019
@vicuna vicuna added the bug label Mar 20, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant