Mantis Bug Tracker
Main | My View | View Issues | Change Log | Roadmap
  

View Issue Details [ Jump to Notes ] [ Issue History ] [ Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0004292OCamlOCamldocpublic2007-05-24 13:212012-03-13 17:36
ReporterHendrik Tews 
Assigned To 
PrioritynormalSeverityminorReproducibilityalways
StatusresolvedResolutionfixed 
PlatformOSOS Version
Product Version3.10.0 
Target VersionFixed in Version4.00.0+dev 
Summary0004292: various documentation problems
DescriptionSome of these points are very minor, but I thought I tell
everything I spotted and let you decide...

0. AGAIN AND AGAIN AND AGAIN: PLEASE MAKE THE SOURCES OF THE
   DOCUMENTATION AVAILABLE [or produce a manual with changes
   information yourself] I am begging for this for years already!

1. the positional specifier for width and precision of printf
   format strings is poorly described

2. the tar file with html version of the manual contains strange
   files, eg manual.haux

3. the comment of UnixLabels.wait_flag refers to module Unix

4. type in Genarray.map_file: default->defaults

5. online doc pointer in
   http://caml.inria.fr/ocaml/release-prev.en.html [^] points to the
   3.10 docs

6. in bscanf, its unclear what "bounding condition" means

7. format6 is missing in the builtin types

8. in the txt version, explanations of embedded modules are
   displaced, for instance "Scanning buffers" appears as headline
   _after_ the contents of the Scanf.Scanning module

9. capiltal format string letters are treated as constructors:
   <code class="code"><span class="constructor">F</span></code>

10. the comment on Pervasives.format4 is general and should
    follow the heading directly

11. wrong open_in in open_in_gen description

12. use the meta symbol class-body in class-expr

13. in the txt version: formatting error in the 3rd case of
    variant-type

14. [might be a feature] some file names have changed, eg
    lex.html instead of manual009.html

15. in the txt version, the first line of embedded output is
    behind the << marker, eg

<<#1+2*3;;
  - : int = 7
   
16. wrong version used:
<<##load "camlp4o.cma";;
      Camlp4 Parsing version 3.10+dev26 (2007-04-25)
TagsNo tags attached.
Attached Files

- Relationships
related to 0001893resolvedprotz various problems/typos in the ocaml doc 

-  Notes
(0004068)
weis (developer)
2007-05-25 09:29

 Points No 4, 6, 10, 11 are corrected in the working sources.
Point 1 will be worked out soon, when the positional specifiers implementation is either finished or abandoned at the end of next month.

Thank you for the careful review.
(0004069)
weis (developer)
2007-05-25 09:34

 Points No 3 also corrected.
(0006895)
doligez (manager)
2012-02-07 15:07

 0: it is now available at http://caml.inria.fr/cgi-bin/viewvc.cgi/ocamldoc/ [^]
1: done (positional specifiers were removed).
2: fixed in trunk [3.13.0] (commit 12138)
5: done by fixing PR#1893
7: fixed in trunk [3.13.0] (commit 12135)
12: fixed in trunk [3.13.0] (commit 12137)
14: it's a feature
15: Not sure what you mean by "behind". It is indented by 2 spaces, which puts it right after the marker.
16: correct in 3.12.1

That leaves us with:
8: but look for "Formatted input channel" instead of "Scanning buffers"
9:
13: should be indented more, but look for "polymorphic-variant-type" instead of "variant-type"

8 and 13 are most probably ocamldoc bugs, not sure about 9.
(0007058)
doligez (manager)
2012-03-13 17:36

 8 is fixed. It was a mistake in Scanf.mli: a missing blank line between the header comment and the module declaration meant that the header comment was the description of the module, which was properly printed after the module declaration by ocamldoc. (commits 12230 and 12231)

13 is a bug/limitation of Hevea, not ocamldoc.

About 9: it's a problem that we'll have to live with. Using another notation in the .mli would make it rather unreadable.

I'm closing this PR.

- Issue History
Date Modified Username Field Change
2007-05-24 13:21 Hendrik Tews New Issue
2007-05-25 09:21 weis Status new => acknowledged
2007-05-25 09:29 weis Note Added: 0004068
2007-05-25 09:34 weis Note Added: 0004069
2012-02-07 14:08 doligez Relationship added related to 0001893
2012-02-07 15:07 doligez Note Added: 0006895
2012-02-07 15:07 doligez Category OCaml documentation => OCamldoc
2012-03-13 17:36 doligez Note Added: 0007058
2012-03-13 17:36 doligez Status acknowledged => resolved
2012-03-13 17:36 doligez Resolution open => fixed
2012-03-13 17:36 doligez Fixed in Version => 4.00.0+dev

Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker