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

Incorrect .TH macro in Arg(3o) #7281

Closed
vicuna opened this issue Jun 29, 2016 · 7 comments
Closed

Incorrect .TH macro in Arg(3o) #7281

vicuna opened this issue Jun 29, 2016 · 7 comments
Assignees

Comments

@vicuna
Copy link

vicuna commented Jun 29, 2016

Original bug ID: 7281
Reporter: olh
Assigned to: @Octachron
Status: resolved (set by @Octachron on 2017-07-24T16:13:20Z)
Resolution: fixed
Priority: normal
Severity: minor
Platform: Linux
OS: openSUSE
OS Version: Tumbleweed
Version: 4.03.0
Target version: later
Fixed in version: 4.06.0 +dev/beta1/beta2/rc1
Category: ocamldoc

Bug description

The troff .TH macro takes up to three extra args, according to the groff documentation at gnu.org. ocamldoc inserts a fourth argument "source:".

Steps to reproduce

$ man Arg | sed -n '1p;$p' | awk '{print $1,$2,$3}'
Arg(3) OCamldoc Arg(3)
2016-06-16 source: Arg(3)

w3m https://www.gnu.org/software/groff/manual/html_node/Man-usage.html

File attachments

@vicuna
Copy link
Author

vicuna commented Jul 21, 2017

Comment author: olh

ocamldoc-man-th.patch is used in openSUSE since a year. It just removes 'source: '. It is not clear to me what the purpose of this extra string is.

@vicuna
Copy link
Author

vicuna commented Jul 21, 2017

Comment author: @Octachron

Thanks for the patch. Looking at the history of ocamldoc, this part of ocamldoc was changed at commit a87c3f2 in order to make the build of the man page reproducible (following a Debian policy). It seems quite probable that "source:" was supposed to be part of the extra-argument, i.e.
"source:"^ "Odoc_mis.current_date". Is there any argument against this choice of extra-argument?

@vicuna
Copy link
Author

vicuna commented Jul 21, 2017

Comment author: olh

Since "Source:" is an extra argument, and thus invalid syntax. The plain date is enough, whatever its exact value is.

With the patch it comes out as:

.TH "Arg" 3 2017-07-17 OCamldoc "OCaml library"

@vicuna
Copy link
Author

vicuna commented Jul 21, 2017

Comment author: @Octachron

According to https://www.gnu.org/software/groff/manual/html_node/Request-and-Macro-Arguments.html, arguments are space separated, therefore
"source:2017-07-17" counts as a single argument. Am I missing something?

@vicuna
Copy link
Author

vicuna commented Jul 21, 2017

Comment author: olh

Without the patch it comes out as:

.TH "Arg" 3 source: 2017-07-17 OCamldoc "OCaml library"

No other man page has the "source:" string. What information does it carry anyway?

@vicuna
Copy link
Author

vicuna commented Jul 23, 2017

Comment author: @Octachron

You are right that this source prefix is not very informative and does not seem common at all. Would you mind sending your patch as a Github PR at https://github.com/ocaml/ocaml ? Otherwise, I would send a slightly reworked patch myself.

@vicuna
Copy link
Author

vicuna commented Jul 24, 2017

Comment author: olh

This was merged via #1259

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants