Remove confusing navigation bar from stdlib documentation #10139
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
dra27
reviewed
Jan 12, 2021
Comment on lines
-7
to
-11
| OCAMLDOC = $(if $(wildcard $(SRC)/ocamldoc/ocamldoc.opt),\ | ||
| $(SRC)/ocamldoc/ocamldoc.opt,\ | ||
| $(SET_LD_PATH) $(SRC)/runtime/ocamlrun $(SRC)/ocamldoc/ocamldoc)\ | ||
| -hide Stdlib -lib Stdlib -nostdlib \ | ||
| -pp "$(AWK) -v ocamldoc=true -f $(SRC)/stdlib/expand_module_aliases.awk" |
There was a problem hiding this comment.
This is a clean-up following #9996
|
Added Changes twice, with differing wording: once it Tools, to mention ocamldoc, once in Documentation, to mention effect. |
|
All changes requested made. |
dra27
reviewed
Jan 12, 2021
|
This seems fine to me (even if I use the next link during reviews from time to time, this is not exactly a feature for most users). Moreover, this navigation bar is also removed by #9755 . |
|
Ok, all done. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Here is a page from the current manual, accessed from index.html --> "The Standard Library" --> "Module bool: boolean values":
https://ocaml.org/releases/4.11/htmlman/libref/Bool.html
It contains a navigation bar, added by ocamldoc when ocaml is built (not when the main manual is built), with "Previous", "Up", and "Next" buttons.
Clicking the "Up" button does not take the user back to the standard library list of modules (from where they have just come), but to an otherwise-unlinked ocamldoc index of modules:
https://ocaml.org/releases/4.11/htmlman/libref/index.html
This is unexpected, and confusing -- the user was browsing the reference manual and is now lost.
This PR simply removes the navbar, and so removes this confusion. In practice, the "Up" button is just the "Back" button in the browser, most of the time. The "Previous" and "Next" buttons are of limited use, since browsing the stdlib module by module is an unusual activity, and can be achieved with the browser back button anyway.
If we want to re-instate "Up", and have it point somewhere sensible (i.e back to the list of stdlib modules in the reference manual), this could be done by the HTML post processor #9755
But I think we should get rid of it.
(This PR also includes two tiny HTML manual related commits which were too small to be separate PRs).
(The change to manual/manual/Makefile removes content which is in fact redundant)