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

manual: refresh moduleref macro #8508

Merged
merged 1 commit into from Mar 16, 2019

Conversation

Projects
None yet
2 participants
@Octachron
Copy link
Contributor

commented Mar 15, 2019

This PR proposes to refresh the \moduleref macro used in the manual. Before this PR, the macro was typically used as

"Hashtabl"[\moduleref{Hashtabl}]

and rendered to

Latex Html
Hashtbl[23.20] Hashtbl[Hashtbl]

With this PR, the latex syntax is simplified to

\stdmoduleref{Hashtbl}

which is rendered to

Latex Html
Hashtbl[23.20] Hashtbl

This PR replaces all uses of \moduleref and few handwritten links with this new \stdref .

@gasche

gasche approved these changes Mar 16, 2019

Copy link
Member

left a comment

This looks nice and useful, thanks.

Could you write a Changes entry?

In the LaTeX output, I don't understand what 23.20 refers to. Is it the Chapter/Section of the PDF rendering of the stdlib documentation? Maybe we don't need the numbers anymore, as long as the PDF output makes it sufficiently clear that the module name itself is clickable (by using a link-specific color)?

(Did we cherry-pick the recent manual improvements #2272 and #2273, which justified this feature, to 4.08? If so, then we should cherry-pick this one as well. If we didn't, maybe we should. @Octachron, can I let you merge and decide for 4.08)

I wonder if it's possible to have a macro for specific identifiers within modules, like {!Foo.bar} in ocamldoc notation. I don't know if we have uses of this in the current manual, but I'm fairly confident that use-cases exist today or in the future.

@Octachron Octachron force-pushed the Octachron:manual_macros branch from 235620a to b316a88 Mar 16, 2019

@Octachron

This comment has been minimized.

Copy link
Contributor Author

commented Mar 16, 2019

The numbering refers to the manual chapter (23 for the standard library chapter) and the section (the latex output has one section by standard library module in lexicographic order). This [chapter.section] numbering is still useful with paper instances of the manual.

I added a Change entry in the 4.08 section: I was planning to cherry-pick this PR and #2272 to 4.08 at the same time. (I had finished the review of #2273 a bit earlier and I have already cherry-picked it).

It would be possible to have a macro for referring components, if the namespace (e.g. type, value, module) is precised, something like:

\stdref[type]{Lazy}{t}

with value as the default namespace. There is however a small caveat (with the current latex output) on the latex side: all references targets a section. For instance, following the link for Array.make leads to the start of the Array section.
I will send a subsequent PR for this macro while I still have the detail in mind.

@gasche

This comment has been minimized.

Copy link
Member

commented Mar 16, 2019

Thanks! Feel free to merge.

(I have forgotten to check that the two manual PRs have a Changes entry. Could you ensure that this is the case, by adding one if necessary?)

@Octachron

This comment has been minimized.

Copy link
Contributor Author

commented Mar 16, 2019

(Both manual PRs already have a Change entry)

@Octachron Octachron merged commit 798dc35 into ocaml:trunk Mar 16, 2019

2 checks passed

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

Octachron added a commit that referenced this pull request Mar 16, 2019

@Octachron

This comment has been minimized.

Copy link
Contributor Author

commented Mar 16, 2019

Cherry-picked on 4.08 with #2272 .

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.