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
remove <h1>title</h1> when an -intro is provided #6928
Comments
Comment author: @dbuenzli Yes please the double line you can see on this page is for example is for example due to this: http://erratique.ch/tmp/opkg-ocamldoc/var/cache/opkg/ocamldoc/bos/index.html |
Comment author: @Octachron Since the two behaviors are quite sensible, I fear that changing unilaterally the behavior of the -intro option may break existing documentations. A more conservative option here may be to add an "-no-main-title" flag to ocamldoc that disables the "h1" title in the html body. Any thoughts on the subject? |
Comment author: @dbuenzli I think what I'm asking is in fact a bit different. I want that if no -title is provided no empty h1 is being generated when -intro is used. That said I would happily use -title to specify the name of the package when I generate the doc set but I didn't do for a usability reason: it generates in the html header titles that have the form "title - Module" for module pages. The problem with this is that when many tabs of packages are open on different modules M1, M2, M3 in your browser you will only see title../title../title.. which is not informative at all. If the title would be generated as "Module - title" you would see then see M1 - t.. / M2 - t... / M3 - t... which makes it easier to select as the module name is in general more discriminating. If you want to witness this try to open many different pages of erratique.ch in your browser until the titles shrink. Had I generated titles as "Erratique/ Page" you'd quickly be lost in the tabs. |
Comment author: @dbuenzli Mmmh in fact now that i think of it I nowadays generate more stuff in my h1. So a |
Comment author: @Octachron So maybe a finer set of improvements would be:
|
Comment author: @dbuenzli Note that for the first and second, given the specification in the docs, we could also avoid introducing a new option and not generate the h1 when -intro is specified and simply call that bug fixing. I'm sure not too many people would actually be affected. I don't understand your third point. No option is needed it's just that currently when -title is specified "title - mod" is generated in the html header title tag, "mod - title" should be generated instead. I don't think this is going to hurt anyone as it is a significant usability improvement. |
This issue has been open one year with no activity. Consequently, it is being marked with the "stale" label. What this means is that the issue will be automatically closed in 30 days unless more comments are added or the "stale" label is removed. Comments that provide new information on the issue are especially welcome: is it still reproducible? did it appear in other contexts? how critical is it? etc. |
Original bug ID: 6928
Reporter: pboutill
Status: confirmed (set by @damiendoligez on 2017-10-20T13:44:11Z)
Resolution: open
Priority: low
Severity: trivial
Version: 4.02.1
Category: ocamldoc
Monitored by: @dbuenzli
Bug description
The documentation says
-8<---
-intro file
Use content of file as ocamldoc text to use as introduction (HTML, LATEX and TeXinfo only). For HTML, the file is used to create the whole index.html file
-8<---
but it is false because it adds the -title in an
at the beginning of the body.
I would like to argue that -title should only change <title> in when a -intro file is provided.
Sorry to bother you with such a detail but it would allow me to put a navbar at the top of the index of my documentation.
Steps to reproduce
touch toto.mli
touch intro
ocamldoc -intro intro -html
cat index.html
File attachments
The text was updated successfully, but these errors were encountered: