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: caml_example for language extensions #939

Merged
merged 7 commits into from Nov 29, 2016

Conversation

Projects
None yet
3 participants
@Octachron
Contributor

Octachron commented Nov 28, 2016

This PR proposes to use the caml_example pseudo-environment in the language extension section of the manual. This section already contains handwritten code example that mimics the output style of the
caml_example pseudo-environment. Moreover, the protection against unexpected errors and warnings in #693 should make safer the use of these environment in this part of the documentation.

The first commit in this PR simply add the possibility to use these environment in exten.etex. The second and third commit convert some examples that were already using handwritten \caml … \endcaml environment and related verbatim environment.

The last commit is (probably) partially unrelated but fixes a missing font-family:monospace style declaration in the generated html − and removes an unneeded hack.

@gasche

This comment has been minimized.

Show comment
Hide comment
@gasche

gasche Nov 28, 2016

Member

This is very nice, and it's enough work that I think there should be a Change entry. One thing you could do is to merge it with the entry for #693.

Member

gasche commented Nov 28, 2016

This is very nice, and it's enough work that I think there should be a Change entry. One thing you could do is to merge it with the entry for #693.

@gasche

This comment has been minimized.

Show comment
Hide comment
@gasche

gasche Nov 28, 2016

Member

(To clarify my thinking a bit, I think some software projects have or give the unfortunate impression that changes to the documentation are of lesser value than changes to the program code. We don't want to do that; in particular, we should not let the people that take some much-needed care of the manual self-censor themselves by downsizing the effort involved.)

Member

gasche commented Nov 28, 2016

(To clarify my thinking a bit, I think some software projects have or give the unfortunate impression that changes to the documentation are of lesser value than changes to the program code. We don't want to do that; in particular, we should not let the people that take some much-needed care of the manual self-censor themselves by downsizing the effort involved.)

Show outdated Hide outdated manual/manual/refman/exten.etex
\endcaml
polymorphic:
\begin{caml_example}[error]
let id: 'a. 'a -> 'a = fun x -> x

This comment has been minimized.

@lavib

lavib Nov 29, 2016

This should be keep fun x -> x+1

@lavib

lavib Nov 29, 2016

This should be keep fun x -> x+1

This comment has been minimized.

@Octachron

Octachron Nov 29, 2016

Contributor

Nice catch! Thanks.

As a side-note, the crucial error here was the missing ;; at the end of the caml_example
that circumvented the status detection for the caml_example. This is fixed in the new version
of the PR.

@Octachron

Octachron Nov 29, 2016

Contributor

Nice catch! Thanks.

As a side-note, the crucial error here was the missing ;; at the end of the caml_example
that circumvented the status detection for the caml_example. This is fixed in the new version
of the PR.

@Octachron

This comment has been minimized.

Show comment
Hide comment
@Octachron

Octachron Nov 29, 2016

Contributor

I have added an item to the Changelog in the manual section: I thought it will be better for readability to not group together changes with quite different objects; even if they share a common internal purpose.

I have also added a missing double semi-colon detection logic for caml_example environments.
Otherwise, such error could circumvent the output status check and lead to discarded code phrase.

Contributor

Octachron commented Nov 29, 2016

I have added an item to the Changelog in the manual section: I thought it will be better for readability to not group together changes with quite different objects; even if they share a common internal purpose.

I have also added a missing double semi-colon detection logic for caml_example environments.
Otherwise, such error could circumvent the output status check and lead to discarded code phrase.

@gasche

This comment has been minimized.

Show comment
Hide comment
@gasche

gasche Nov 29, 2016

Member

@lavib if you wanted to be credited as a reviewer in the Changelog, which name would you prefer us to use? (Usually we use real-name-looking names, but some people have other preferences.) Did you review the whole PR, or just randomly peeked and saw this one issue?

Member

gasche commented Nov 29, 2016

@lavib if you wanted to be credited as a reviewer in the Changelog, which name would you prefer us to use? (Usually we use real-name-looking names, but some people have other preferences.) Did you review the whole PR, or just randomly peeked and saw this one issue?

@lavib

This comment has been minimized.

Show comment
Hide comment
@lavib

lavib Nov 29, 2016

lavib commented Nov 29, 2016

@gasche gasche merged commit 4c04dee into ocaml:trunk Nov 29, 2016

2 checks passed

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

This comment has been minimized.

Show comment
Hide comment
@gasche

gasche Nov 29, 2016

Member

Ok, I went ahead and merged then. Thanks for the nice work!

Member

gasche commented Nov 29, 2016

Ok, I went ahead and merged then. Thanks for the nice work!

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

Merge pull request #939 from Octachron/manual_camlexample_for_exten
Manual: caml_example for language extensions
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment