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

PR#6597: manual, forward references to languages extensions #1030

Merged
merged 10 commits into from Feb 5, 2017

Conversation

Projects
None yet
2 participants
@Octachron
Contributor

Octachron commented Feb 4, 2017

PR#6597

This PR adds some forward references to language extensions inside the main language reference section,
with the aim to decrease −at least a little− the fragmentation of the description of the grammar of current OCaml.

More precisely, after each description of non-terminal symbols, this PR references all language extensions
that extends these symbols.

These references are added as plain text rather than footnotes to give them some amount of visibility.

@gasche

This comment has been minimized.

Show comment
Hide comment
@gasche

gasche Feb 4, 2017

Member

How are the \ref{..} rendered? Because if the result is just "See also 5.14, 6.17 and 8.3", then I don't see how people would ever click on those. I would need to at least have a human-readable description of the content of the pointed section to discover them (for example, if I'm looking for a syntactic construction in the manual and I don't find it in the main section, maybe the name of the extensions lets me focus on a few that might be responsible for this construction, and rule out the unrelated ones).

Member

gasche commented Feb 4, 2017

How are the \ref{..} rendered? Because if the result is just "See also 5.14, 6.17 and 8.3", then I don't see how people would ever click on those. I would need to at least have a human-readable description of the content of the pointed section to discover them (for example, if I'm looking for a syntactic construction in the manual and I don't find it in the main section, maybe the name of the extensions lets me focus on a few that might be responsible for this construction, and rule out the unrelated ones).

@Octachron

This comment has been minimized.

Show comment
Hide comment
@Octachron

Octachron Feb 4, 2017

Contributor

A fine point. Indeed, the reference were rendered as 7.21 etc…
I have converted to hyperref using the section name as a short description.

Contributor

Octachron commented Feb 4, 2017

A fine point. Indeed, the reference were rendered as 7.21 etc…
I have converted to hyperref using the section name as a short description.

Show outdated Hide outdated Changes
@@ -94,6 +94,10 @@ Next version (4.05.0):
### Manual and documentation:
- PR#6597: add forward references to language extensions that

This comment has been minimized.

@gasche

gasche Feb 4, 2017

Member

You should also include GPR#1030. Otherwise the PR seems good to go.

@gasche

gasche Feb 4, 2017

Member

You should also include GPR#1030. Otherwise the PR seems good to go.

@gasche gasche merged commit 40a9130 into ocaml:trunk Feb 5, 2017

2 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

camlspotter pushed a commit to camlspotter/ocaml that referenced this pull request Oct 17, 2017

Merge pull request #1030 from Octachron/ocaml-manual-forward-refs
PR#6597:  manual, forward references to languages extensions
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment