0007635: ocamldoc does not generate HTML linkable IDs for modules

(0018302)
yawaramin (reporter)
2017-09-21 05:56

Sorry, forgot to mention how the module span looks like:

<span class="keyword">module</span>

(0018307)
octachron (developer)
2017-09-21 11:33

It is true that submodule items are not given a specific id. However, submodules are fully expanded in a separate page ("Main.Submodule.html"), thus it is still possible to link to a specific submodule.

Do you have any example where it would make sense to link to "Main.html#MODULEA" rather than "Main.A.html"?

(0018309)
yawaramin (reporter)
2017-09-21 15:09
edited on: 2017-09-21 15:13

My goal is to allow generating a table of contents for each module doc page. E.g., for the module sig above, I would want to generate the following TOC:

(ul)
  (li class="module")(a href="#MODULEA")A(/a)(/li)
  (li class="type")(a href="#TYPEa")a(/a)(/li)
  (li class="val")(a href="#VALa1")a1(/a)(/li)
(/ul)

(Using parens instead of angle brackets here because otherwise Mantis is trying to format as HTML. I would also include after the closing </a> tag the first sentence of the item's doc comment, for ease of reference.)

To make this possible, it would be good to have that 'MODULEA' ID, e.g. Otherwise if the user clicked on types and values in the TOC they would be jumped down to the main documentation for the item, in the same page; but if they clicked on a module they would be jumped to another page, which would be confusing.

(0018420)
octachron (developer)
2017-09-30 14:34

See https://github.com/ocaml/ocaml/pull/1383 [^] for a possible implementation.

(0018432)
octachron (developer)
2017-09-30 23:25

Fixed by merging the above PR in trunk.

(0018433)
yawaramin (reporter)
2017-09-30 23:34

@octachron nice! I'm rebasing on this now, will send PR soon.

Issue History
Date Modified	Username	Field	Change
2017-09-21 05:54	yawaramin	New Issue
2017-09-21 05:56	yawaramin	Note Added: 0018302
2017-09-21 11:33	octachron	Note Added: 0018307
2017-09-21 15:09	yawaramin	Note Added: 0018309
2017-09-21 15:11	yawaramin	Note Edited: 0018309	View Revisions
2017-09-21 15:13	yawaramin	Note Edited: 0018309	View Revisions
2017-09-22 15:53	octachron	Assigned To	=> octachron
2017-09-22 15:53	octachron	Status	new => assigned
2017-09-30 14:34	octachron	Note Added: 0018420
2017-09-30 21:34	yawaramin	Tag Attached: ocamldoc
2017-09-30 23:25	octachron	Note Added: 0018432
2017-09-30 23:25	octachron	Status	assigned => resolved
2017-09-30 23:25	octachron	Fixed in Version	=> later
2017-09-30 23:25	octachron	Resolution	open => fixed
2017-09-30 23:34	yawaramin	Note Added: 0018433

Notes
(0018302) yawaramin (reporter) 2017-09-21 05:56	Sorry, forgot to mention how the module span looks like: <span class="keyword">module</span>

(0018307) octachron (developer) 2017-09-21 11:33	It is true that submodule items are not given a specific id. However, submodules are fully expanded in a separate page ("Main.Submodule.html"), thus it is still possible to link to a specific submodule. Do you have any example where it would make sense to link to "Main.html#MODULEA" rather than "Main.A.html"?

(0018309) yawaramin (reporter) 2017-09-21 15:09 edited on: 2017-09-21 15:13	My goal is to allow generating a table of contents for each module doc page. E.g., for the module sig above, I would want to generate the following TOC: (ul) (li class="module")(a href="#MODULEA")A(/a)(/li) (li class="type")(a href="#TYPEa")a(/a)(/li) (li class="val")(a href="#VALa1")a1(/a)(/li) (/ul) (Using parens instead of angle brackets here because otherwise Mantis is trying to format as HTML. I would also include after the closing </a> tag the first sentence of the item's doc comment, for ease of reference.) To make this possible, it would be good to have that 'MODULEA' ID, e.g. Otherwise if the user clicked on types and values in the TOC they would be jumped down to the main documentation for the item, in the same page; but if they clicked on a module they would be jumped to another page, which would be confusing.

(0018420) octachron (developer) 2017-09-30 14:34	See https://github.com/ocaml/ocaml/pull/1383 [^] for a possible implementation.

(0018432) octachron (developer) 2017-09-30 23:25	Fixed by merging the above PR in trunk.

(0018433) yawaramin (reporter) 2017-09-30 23:34	@octachron nice! I'm rebasing on this now, will send PR soon.

Relationships