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

ocamldoc, manpage backend: unwrap module comment docstrings #2114

Merged
merged 3 commits into from Oct 24, 2018

Conversation

Projects
None yet
2 participants
@Octachron
Copy link
Contributor

commented Oct 22, 2018

Currently, the manpage back-end of ocamldoc wraps module (and class) comments inside a code environment. For instance, the floating-point arithmetic introduction is rendered as

.B === 
.B Floating\-point arithmetic
.B 
.B 
.B    OCaml\&'s floating\-point numbers follow the
.B    IEEE 754 standard, using double precision (64 bits) numbers\&.
.B    Floating\-point operations never raise an exception on overflow,
.B    underflow, division by zero, etc\&.  Instead, special IEEE numbers
.B    are returned as appropriate, such as infinity for 1\&.0 /\&. 0\&.0,
...

(There is a similar problem with the format introduction)
This PR proposes to remove this wrapping, to restore emphasis within the documentation comment

.B Floating\-point arithmetic
.sp
OCaml\&'s floating\-point numbers follow the
IEEE 754 standard, using double precision (64 bits) numbers\&.
Floating\-point operations never raise an exception on overflow,
underflow, division by zero, etc\&.  Instead, special IEEE numbers
are returned as appropriate, such as 
.B infinity
for 
.B 1\&.0 /\&. 0\&.0
,
...

Another advantage is that it becomes possible to use man-specific, {%man:...%} content inside those module comments.

@gasche

This comment has been minimized.

Copy link
Member

commented Oct 23, 2018

I had noticed a problem with the Format manpage before, this may fix it! How did you test/validate the change for absence of regression?

@Octachron

This comment has been minimized.

Copy link
Contributor Author

commented Oct 23, 2018

If the problem in Format manpage was that a lot of text was bold, this seems fixed.

In term of testing, I merely used a mixture of diffing the resulting manpages before and after this PR (from the manpages target) and some visual confirmation for the new manpages.

Moreover, the toplevel comment of each module was already rendered with man_of_text, thus we are not in untested waters.

A possibly gratuitous change with this PR is the removal of === around titles.
For instance, we could render the Floating-point arithmetic title as

.B ===
.B Floating\-point arithmetic
.B ===

rather than just

.B Floating\-point arithmetic
@gasche

This comment has been minimized.

Copy link
Member

commented Oct 23, 2018

I'm satisfied with your testing strategy and will approve of the change.

I think that it would be nice to keep some kind of title markup, because in your example above the title seems to be rendered in the exact same way as infinity below. === works, # (markdown-style) would also be a choice. Groff seems to support headings with .NH (for numbered headings) and .SH (for unnumbered headings), maybe one of these would do?

@Octachron

This comment has been minimized.

Copy link
Contributor Author

commented Oct 23, 2018

.SH sections are generally used for the traditional manpage section (e.g. NAME SYNOPSIS ). But using subsection .SS seems like a good idea, this yields a bold heading at half the indentation of text

Section
  Subsection
    text
@gasche

This comment has been minimized.

Copy link
Member

commented Oct 23, 2018

.SS Floating\-point arithmetic
.sp
OCaml\&'s floating\-point numbers follow the
IEEE 754 standard, using double precision (64 bits) numbers\&.
Floating\-point operations never raise an exception on overflow,
underflow, division by zero, etc\&.  Instead, special IEEE numbers
are returned as appropriate, such as 
.B infinity
for 
.B 1\&.0 /\&. 0\&.0
,
...
@gasche

gasche approved these changes Oct 23, 2018

@Octachron Octachron force-pushed the Octachron:stdlib_precedence_table branch from ce69f88 to 67d1e3d Oct 24, 2018

@Octachron Octachron merged commit 50da048 into ocaml:trunk Oct 24, 2018

2 checks passed

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

damiendoligez added a commit to damiendoligez/ocaml that referenced this pull request Nov 5, 2018

ocamldoc, manpage backend: unwrap module comment docstrings (ocaml#2114)
* unwrap non-code doctstring
* use .SS for ocamldoc titles
* update Changes
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.