Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0005407OCamlOCamldocpublic2011-11-24 08:562013-05-07 14:35
ReporterMartin Jambon 
Assigned Toguesdon 
PrioritynormalSeverityfeatureReproducibilityN/A
StatusassignedResolutionreopened 
PlatformOSOS Version
Product Version3.12.1 
Target VersionFixed in Version 
Summary0005407: Inline submodules, single-page HTML
DescriptionWould it be possible to have the two following options:

1. keep the documentation of submodules on the same HTML page as the parent module (or compilation unit)

2. produce a single HTML page instead of about one per source file (implies option (1))

Both would make search easier, especially when the modules or submodules are many and small.
Steps To ReproduceThis is a very specific need. I suggest you develop your own custom generator for that (not much work: some methods to override).
Tagshtml, ocamldoc
Attached Files

- Relationships

-  Notes
(0007080)
Martin Jambon (reporter)
2012-03-14 22:20

This doesn't strike me as particularly specific. How do you search for a given functionality within a library?
(0007081)
guesdon (manager)
2012-03-14 22:26

grepping in mli files ?
Argot is what you're looking for: http://argot.x9c.fr/ [^]
It includes a local search capability, including searching on type and handling type isomorphism.
(0007082)
Martin Jambon (reporter)
2012-03-14 23:45

While I appreciate the effort made by Argot, what I really want is native full-text search (Ctrl-f) that would be straightforward if ocamldoc-generated manuals came in a single-page variant, just like OMake's manual (http://omake.metaprl.org/manual/omake.html [^]) atdgen's manual produced with Hevea (http://oss.wink.com/atdgen/atdgen-1.2.2/manual/atdgen-manual.html [^]), the GNU Emacs manual (http://www.gnu.org/software/emacs/manual/emacs.html [^]) and others.

I think it would benefit a large number of users without requiring any special-purpose search mechanism.

I don't completely exclude to do it myself, but it seems more easily done by the original author. Also the patch would need to be integrated in the official OCaml distribution.
(0007107)
guesdon (manager)
2012-03-20 07:56

Another solution would be to generate a latex document, then use hevea to translate it to html :-)

I don't have time to develop this new generator, but if you create it, we can integrate it.

Here is how I see it:
- It would be an extension of the default html generator, so you can develop it separately,
- After integration, it would be choosen with a -one-html option.

You will have to handle, in links, the fact that everything is in one file. If it appears that it would be made easier if the Odoc_html.Naming module was a class, to change some methods, just tell me.

At last, interface to define a custom generator will change in next release, you can have a loot, for example, at
  https://gitorious.org/ocamldoc-generators/ocamldoc-generators/blobs/master/odoc_todo.ml [^]
(if you already use the ocaml-4.00 branch)
(0007111)
frisch (developer)
2012-03-20 10:52

We would also like to have the option to generate sub-modules on the same HTML page. (No real need on our side to generate everything on one big page.) A related topic: another option to "inline" included signatures.
(0009249)
lebedev (reporter)
2013-05-07 12:08

Having an option, which allows to inline included signatures would be useful. See for example how Core containers are documented [1, 2], each module includes a private signature 'Creators', which is not accessible via the generated documentation.

[1]: https://ocaml.janestreet.com/ocaml-core/latest/doc/core/Hashtbl.Poly.html [^]
[2]: https://ocaml.janestreet.com/ocaml-core/latest/doc/core/Hash_set.html [^]

- Issue History
Date Modified Username Field Change
2011-11-24 08:56 Martin Jambon New Issue
2011-11-24 08:56 Martin Jambon Status new => assigned
2011-11-24 08:56 Martin Jambon Assigned To => guesdon
2011-11-24 08:58 Martin Jambon Tag Attached: ocamldoc
2011-11-24 08:58 Martin Jambon Tag Attached: html
2012-03-14 21:52 guesdon Status assigned => closed
2012-03-14 21:52 guesdon Resolution open => won't fix
2012-03-14 21:52 guesdon Steps to Reproduce Updated View Revisions
2012-03-14 22:20 Martin Jambon Note Added: 0007080
2012-03-14 22:20 Martin Jambon Status closed => feedback
2012-03-14 22:20 Martin Jambon Resolution won't fix => reopened
2012-03-14 22:26 guesdon Note Added: 0007081
2012-03-14 23:45 Martin Jambon Note Added: 0007082
2012-03-14 23:45 Martin Jambon Status feedback => assigned
2012-03-20 07:56 guesdon Note Added: 0007107
2012-03-20 10:52 frisch Note Added: 0007111
2013-05-07 12:08 lebedev Note Added: 0009249


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker