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

various problems in the ocaml documentation #5149

Closed
vicuna opened this issue Sep 16, 2010 · 12 comments
Closed

various problems in the ocaml documentation #5149

vicuna opened this issue Sep 16, 2010 · 12 comments

Comments

@vicuna
Copy link

vicuna commented Sep 16, 2010

Original bug ID: 5149
Reporter: Hendrik Tews
Assigned to: @zoggy
Status: closed (set by @xavierleroy on 2015-12-11T18:23:47Z)
Resolution: fixed
Priority: normal
Severity: feature
Version: 3.12.0
Target version: 4.01.0+dev
Fixed in version: 4.01.0+dev
Category: ocamldoc
Monitored by: @glondu

Bug description

I spotted the following errors/problems in the ocaml documentation:

  1. The parser examples in 1.8 only show the error "Reference to
    undefined global `Dynlink'"

  2. In 3.12 the example after "However, the domain of the coercion
    cannot be omitted here": does work now!

  3. Option -vnum of ocamlyacc is not documented

  4. The conditions on caml_register_generational_global_root make
    it useless, because one has to register before storing a valid
    value and one must not change it after registration, thus
    generational global roots can only contain invalid values!
    (Probably related to issue About generational global roots in the manual #4743).

  5. The doc of Pervasives.atan2 speaks about atan.

  6. The meaning of the type parameters 'd, 'e and 'f of format6
    are still undocumented.

  7. In the txt version, the intro for nested modules is displaced,
    see for instance Map.OrderedType. (This is related to point 8
    of various documentation problems #4292)

  8. The doc of Scanf.Scanning.open_in speaks about from_file.

  9. In the doc of Scanf, the subitemize for conversion `s' is not
    formatted correctly.

  10. In the txt version references to subsections like "with a
    special case for {!Scanf.space}" in scanf.mli do not work:
    They are formatted as "with a special case for [20.27]" but
    20.27 is the Scanf Section!

  11. Sys.is_directory is present since 3.10.

  12. The windows status "ditto" of Unix.out_channel_of_descr,
    which expanded to "...works under NT, 2000, XP" in 3.11
    expands now to "not implemented". Is this really the case?

  13. UnixLabels has been forgotten during the update, it is not in
    sync with Unix any more, see

    • process_status : WSTOPPED
    • utimes
    • setgroups
    • initgroups
    • socket_domain : PF_INET6
  14. The module MoreLabels is missing in the txt version.

  15. The line break in the html backend does not always work. For
    instance MoreLabels.Map.S.html is all in one line.

  16. Some of the expanded meta symbols in 7 are not hot on the
    left hand side, so that one can not easily jump to it:

    • pattern in 7.11
    • let-binding in 7.12
    • parameter in 7.13
    • module-type in 7.15
    • mod-constraint in 7.16
    • class-field in 7.17
@vicuna
Copy link
Author

vicuna commented Oct 5, 2010

Comment author: @xclerc

Item 9 is fixed in "version/3.12" by revision 10705.

@vicuna
Copy link
Author

vicuna commented Oct 12, 2010

Comment author: @damiendoligez

Item 11 fixed in 3.12.1+dev5
Item 3 will be fixed with the release of 3.13.0

@vicuna
Copy link
Author

vicuna commented Feb 9, 2011

Comment author: matthias-goergens

I've just hit item 1 myself. You can fix it by loading

#load "dynlink.cma";;

first.

@vicuna
Copy link
Author

vicuna commented Mar 6, 2011

Comment author: @pierreweis

Item 5 is fixed in version 3.12.1
Item 8 is fixed in 3.12.1+dev6
Item 10 is fixed in 3.12.1+dev6
Item 13 is fixed in 3.12.1+dev6

@vicuna
Copy link
Author

vicuna commented May 17, 2011

Comment author: @damiendoligez

fixed 2, 4, 6, 12.
item 1 was fixed for another report

REMAIN TO BE FIXED: 7, 14, 15, 16

@vicuna
Copy link
Author

vicuna commented Jul 10, 2012

Comment author: @damiendoligez

point 7: there is no intro for OrderedType. Point 8 of 4292 was fixed by inserting a blank line in the .mli
point 14: fixed
point 15: as far as I can tell, this only affects MoreLabels and StdLabels and their sub-modules. At any rate, this is a small problem, since the HTML is still correct and displays correctly.
point 16: will need some hacking on our TeX and Hevea files.

REMAIN TO BE FIXED: 15 and 16

@vicuna
Copy link
Author

vicuna commented Aug 2, 2012

Comment author: Hendrik Tews

I don't believe item 4 has been fixed. The 4.00 documentation still says one should register before storing a valid value and one should not change the value after registration. As a consequence all generational global roots must contain invalid values!

@vicuna
Copy link
Author

vicuna commented Feb 19, 2013

Comment author: @damiendoligez

Point 16 has been fixed at some point.

REMAINING:
4
15 (probably an ocamldoc problem)

@vicuna
Copy link
Author

vicuna commented Jul 11, 2013

Comment author: @damiendoligez

Point 4 was fixed in rev 11047 by changing the wording of the doc.

About the only remaining point (15): it looks like ocamldoc never bothers inserting any line breaks, the only one I can see are from the source files.

I'm downgrading this to an ocamldoc feature request.

@vicuna
Copy link
Author

vicuna commented Aug 5, 2013

Comment author: @zoggy

I don't understand point 15: "The line break in the html backend does not always work. For instance MoreLabels.Map.S.html is all in one line."

Looking at http://caml.inria.fr/pub/docs/manual-ocaml-4.00/libref/MoreLabels.Map.S.html, what is "all in one line" ?

@vicuna
Copy link
Author

vicuna commented Aug 11, 2013

Comment author: Hendrik Tews

Hi,

point 15 is just a remark: While most ocamldoc generated html
files contain reasonable line breaks in the html sources, the
html source for MoreLabels.Map.S.html contains one very very long
line.

I thought someone may be interested in this point, if not just
close this issue.

Bye,

Hendrik

@vicuna
Copy link
Author

vicuna commented Aug 12, 2013

Comment author: @zoggy

Since revisions 13990 (branch 4.01) and 13991 (trunk), line breaks are now added before pre tags. This should make html source more readable.

@vicuna vicuna closed this as completed Dec 11, 2015
@vicuna vicuna added this to the 4.01.0 milestone Mar 14, 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