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

ocamldoc, heading tags inside spans tags is illegal in html #5111

Closed
vicuna opened this issue Jul 21, 2010 · 8 comments
Closed

ocamldoc, heading tags inside spans tags is illegal in html #5111

vicuna opened this issue Jul 21, 2010 · 8 comments

Comments

@vicuna
Copy link

@vicuna vicuna commented Jul 21, 2010

Original bug ID: 5111
Reporter: @dbuenzli
Assigned to: @zoggy
Status: closed (set by @xavierleroy on 2015-12-11T18:23:54Z)
Resolution: fixed
Priority: normal
Severity: minor
Version: 3.12.0+beta1 or 3.12.0+rc1
Target version: 4.01.0+dev
Category: ocamldoc
Monitored by: @dbuenzli

Bug description

ocamldoc puts heading tags inside spans, as a result the pages are not valid html. It seems the only reason this is done is to put an id attribute on the heading but this can be put directly on the heading tag.

Note that in general the structure of the generated html could be reviewed to make it easier to style the output with css. For example there are quite a few annoying < br/> and < center> tags. Also there are empty < pre>< /pre> tags surrounding code blocks introduced with {[]} maybe the code block is supposed to be enclosed in a < pre> tag (?). There is also some untagged text in the body of the document, e.g. the first line under the module definition at the top of a module page.

Best,

Daniel

@vicuna
Copy link
Author

@vicuna vicuna commented Jul 21, 2010

Comment author: @dbuenzli

Of course ocamlbuild should be subtituted by ocamldoc [ed: done]. And apparently mantis doesn't escape html properly [ed: fixed it by inserting a space after each <]. So here's again the text of the report :

ocamldoc puts heading tags inside spans, as a result the pages are not valid html. It seems the only reason this is done is to put an id attribute on the heading but this can be put directly on the heading tag.

Note that in general the structure of the generated html could be reviewed with appropriate class attributes to make it easier to style the output with css. There are also quite a few annoying br and center tags.

Also there are empty pre tag surrounding code blocks introduced with the syntax {[ ]} maybe the code block is supposed to be enclosed in a pre tag itself (?).

There is also some untagged text in the body of the document e.g. the first line under the module definition at the top of a module page.

Best,

Daniel

@vicuna
Copy link
Author

@vicuna vicuna commented Jul 24, 2010

Comment author: @dbuenzli

Its also seems that type definition for records are not enclosed in pre tags.

@vicuna
Copy link
Author

@vicuna vicuna commented Aug 27, 2012

Comment author: @zoggy

Revisions 12886 (branch 4.00) and revision 12887 (trunk) fix the problem with the span around hX tags.

@vicuna
Copy link
Author

@vicuna vicuna commented Aug 27, 2012

Comment author: @zoggy

Regarding records definitions, it seems enclosed in < pre> now.

What do you mean about "some untagged text in the body of the document e.g. the first line under the module definition at the top of a module page." ?

@vicuna
Copy link
Author

@vicuna vicuna commented Sep 19, 2012

Comment author: @dbuenzli

I mean the top level "List operations" here http://caml.inria.fr/pub/docs/manual-ocaml-4.00/libref/List.html

@vicuna
Copy link
Author

@vicuna vicuna commented Sep 25, 2012

Comment author: @zoggy

Ok. All description is now put into a div class="info" (idem for module types, classes and class types).
Revision 12593 in version/4.00 and 12594 in trunk.

@vicuna
Copy link
Author

@vicuna vicuna commented Mar 3, 2013

Comment author: @dbuenzli

Regarding Revision 12594. Would it be possible to characterize the div class="info" with more precise qualifiers e.g. div class = "info module synopsis" (module inside a module), div class = "info module description". Since for now it is impossible to distinguish toplevel module descriptions if you indent "info" divs for elements of a signature then the toplevel module description also gets indented.

To see what I mean see here [1], I would like to align the top level module text with the documentation text in the Basics section.

[1] http://erratique.ch/software/cmdliner/doc/Cmdliner

If you indent the info for values and module

@vicuna
Copy link
Author

@vicuna vicuna commented Aug 5, 2013

Comment author: @zoggy

Now module, module type, class and class type comments at the beginning of a page are in a

, where X is, respectively, "module", "modtype", "class", "classtype".

Rev 13981 in 4.01.
Rev 13982 in trunk.

This should be enough for you to prevent unwanted indentation. Is it ok ?

More generally, the HTML generator could output more precise classes for each element of the generated document. If you have time to make a proposition about this, do not hesitate.

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