Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0007108OCamlocamldocpublic2015-12-27 15:172017-09-24 17:31
ReporterArmael 
Assigned Togasche 
PrioritynormalSeveritytweakReproducibilityalways
StatusclosedResolutionfixed 
PlatformOSOS Version
Product Version 
Target VersionFixed in Version4.03.0+dev / +beta1 
Summary0007108: Standard generators override custom generators
DescriptionThis is a known (and documented) behavior: standard generators, loaded with e.g. the -html, -latex, ... options, override custom generators provided with option -g. This is a bit inconvenient, at least when using custom generators with ocamlbuild (see for example https://github.com/Armael/ocaml-libudev/blob/master/myocamlbuild.ml#L40 [^] or https://github.com/ocsigen/tyxml/blob/master/myocamlbuild.ml#L57 [^] for a workaround). gasche suggested (https://github.com/ocaml/ocamlbuild/issues/10#issuecomment-166849495 [^]) that the cleanest solution could be to change ocamldoc's behavior regarding this.

I could submit a PR where custom generators would always be loaded after standard ones, if this sounds like a satisfying solution.
TagsNo tags attached.
Attached Filespatch file icon generators2.patch [^] (4,036 bytes) 2016-01-02 01:21 [Show Content]

- Relationships

-  Notes
(0015195)
gasche (administrator)
2015-12-27 18:51
edited on: 2015-12-28 11:07

More precisely, I think that when a custom generator is defined by extending the html generator, as in the documentation example
  http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sec333 [^]
, then passing the -html option should be valid and select the extended generator (and likewise when extending another generator and passing the corresponding option).

Having a quick look at the codebase, it looks like this would be rather natural to do: in the code of the -html, -latex etc. command-line options
  https://github.com/ocaml/ocaml/blob/031cffd1554cde5e9d78b78e4959708a2d8c9201/ocamldoc/odoc_args.ml#L266-L281 [^]
instead of calling set_generator with the base generators, use the get_foo_generator functions of
  https://github.com/ocaml/ocaml/blob/031cffd1554cde5e9d78b78e4959708a2d8c9201/ocamldoc/odoc_args.ml#L19-L51 [^]

Of course this is only a suspicion, one would need someone motivated to implement and test the change and report on it.

(0015196)
Armael (manager)
2015-12-28 15:04

I see. Would the attached patch implement what you describe?
(I did not use the get_foo_generator functions as the raise an exception when the current generator is not of the expected kind - in this case I guess we just want to overwrite it)
(0015197)
gasche (administrator)
2015-12-28 15:22

I think that would be fine. Your gentler change (than raising an exception) also has the advantage that, if people insist on the previous behaviour, they can simply replace "-html" by "-man -html" as a workaround.

Did you test it on previously failing cases, or in the context of ocamlbuild#10? If yes, and if it works, I'll merge it; but can you add a Changes entry?
(0015207)
gasche (administrator)
2016-01-01 22:34

Armal: Ping? If you can confirm that this patch fixes the previous ocamldoc+ocamlbuild issues, I would be happy to merge it in 4.03 -- but then we should not wait to long.
(0015208)
Armael (manager)
2016-01-02 01:20

Sorry for the delay. I tested the patch in the context of ocamlbuild#10: more precisely, using this self-contained example: https://github.com/Armael/manual-ocamlbuild/tree/custom-generator/examples/07-ocamldoc-custom-generator [^] .

Attached is a new patch (generators2.patch) with a Changes entry, and small changes to the manual to update the documentation.
(0015209)
Armael (manager)
2016-01-02 01:24

Oh, and the patch seems to work.
(0015210)
gasche (administrator)
2016-01-02 07:04

Merged in trunk,
  https://github.com/ocaml/ocaml/commit/f60e1d7a5c8df3e2d4cf134e64e81b16df9ee342 [^]

Thanks!

- Issue History
Date Modified Username Field Change
2015-12-27 15:17 Armael New Issue
2015-12-27 18:51 gasche Note Added: 0015195
2015-12-27 18:51 gasche Note Edited: 0015195 View Revisions
2015-12-28 11:06 gasche Severity minor => tweak
2015-12-28 11:07 gasche Note Edited: 0015195 View Revisions
2015-12-28 15:04 Armael Note Added: 0015196
2015-12-28 15:04 Armael File Added: generators.patch
2015-12-28 15:22 gasche Note Added: 0015197
2015-12-28 15:23 gasche Status new => confirmed
2016-01-01 22:34 gasche Note Added: 0015207
2016-01-02 01:20 Armael Note Added: 0015208
2016-01-02 01:21 Armael File Added: generators2.patch
2016-01-02 01:24 Armael Note Added: 0015209
2016-01-02 06:56 gasche File Deleted: generators.patch
2016-01-02 07:04 gasche Note Added: 0015210
2016-01-02 07:04 gasche Status confirmed => resolved
2016-01-02 07:04 gasche Fixed in Version => 4.03.0+dev / +beta1
2016-01-02 07:04 gasche Resolution open => fixed
2016-01-02 07:04 gasche Assigned To => gasche
2017-02-23 16:46 doligez Category OCamldoc => ocamldoc
2017-09-24 17:31 xleroy Status resolved => closed


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker