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

remove <h1>title</h1> when an -intro is provided #6928

Closed
vicuna opened this issue Jul 12, 2015 · 7 comments
Closed

remove <h1>title</h1> when an -intro is provided #6928

vicuna opened this issue Jul 12, 2015 · 7 comments

Comments

@vicuna
Copy link

vicuna commented Jul 12, 2015

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

@vicuna
Copy link
Author

vicuna commented Sep 10, 2016

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

@vicuna
Copy link
Author

vicuna commented Sep 13, 2016

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?

@vicuna
Copy link
Author

vicuna commented Sep 13, 2016

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.

@vicuna
Copy link
Author

vicuna commented Sep 13, 2016

Comment author: @dbuenzli

Mmmh in fact now that i think of it I nowadays generate more stuff in my h1. So a
-no-intro-title would still be useful for me so that I can still use -title aswell and control my intro h1.

@vicuna
Copy link
Author

vicuna commented Sep 13, 2016

Comment author: @Octachron

So maybe a finer set of improvements would be:

  • First, do not generate empty intro h1 (which does seem like an unconditionnal improvement)
  • Second, an option to suppress the in-body intro title to give more control to the intro option
  • Third, a subtitle option that would be suffixed to the inner title rather than prefixed like the title option.

@vicuna
Copy link
Author

vicuna commented Sep 13, 2016

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.

@github-actions
Copy link

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.

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