Opened 8 years ago

Closed 7 years ago

#656 closed defect (fixed)

manpage improvements from Debian package

Reported by: Jonathan Dowland Owned by: Christian Franke
Priority: minor Milestone: Release 6.6
Component: all Version: 6.4
Keywords: man Cc:

Description

Hi, please find enclosed a patch we received in the Debian BTS to improve the manpages. The patch has a header which explains the improvements (lots of groff convention fix-ups and consistency changes etc.) Please let me know if you don't like this.

I have a few more patches from the Debian package to submit which I will do in due course.

Attachments (1)

50_manpage_improvements.diff (66.6 KB ) - added by Jonathan Dowland 8 years ago.
patch

Download all attachments as: .zip

Change History (5)

by Jonathan Dowland, 8 years ago

patch

in reply to:  description comment:1 by Christian Franke, 8 years ago

Milestone: undecided

Thanks!

Why does the patch only cover smartd.conf ?

Are all changes compatible to man page syntax flavors of our other platforms (*BSD, Darwin) and with man2html ?

In particular: Are \(aq and \(en always available ?

BTW: This change of the patch looks interesting:

-\fBsmartd\fP. 
...
+\fBsmartd\fP.m46

and results in:
... message string from smartd.m46 This message ...

comment:2 by Alex Samorukov, 8 years ago

I tested proposed patches and it seems to works fine on Darwin (OSX). man2html also works correctly (tested with 3.0.1). m46 seems to be a typo. Please correct the patch and add, if possible, other man files if you want this to be accepted.

comment:3 by Christian Franke, 7 years ago

Component: smartdall
Keywords: man added; docs removed
Milestone: undecidedRelease 6.6
Owner: set to Christian Franke
Status: newaccepted
Type: patchdefect

Patch does no longer apply without conflict. I will add the suggested changes to all man pages manually.

The usage of \(aq may or may not introduce portability problems in practice. It was not part of the traditional *roff syntax. Man pages generated with Pod::Man Perl module use \*(Aq instead and set this register to \(aq if and only if groff is used:

.ie \n(.g .ds Aq \(aq
.el       .ds Aq '

Results from some research with various older and historic VMs:

Is \(aq supported by standard man command ?

  • OpenIndiana 2016.10: yes
  • OpenBSD 5.0 (2011): yes
  • man2html 1.6g-6 from Debian (2011): yes
  • man2html from upstream man-1.6g (2010?, no longer maintained): NO!
  • NetBSD 5.0.2 (2010, groff 1.19.2): yes
  • FreeBSD 8.0 (2009, groff 1.19.2): yes
  • OpenSolaris 2009-06: NO! (\(en: also NO!)
  • ... (time travel) ...
  • Slackware 1.1.2 (1994, Linux 0.99.15, groff 1.08): yes
  • Slackware 1.0.1 (1993, Linux 0.99.12, groff 1.05): no

So no problem on Linux :-).

Possible problems could occur with older but still active Solaris and unpatched man2html versions (Mac OS: unknown). Could be handled by the approach used by Pod::Man or by some extension to MAN_FILTER in Makefile.am.

comment:4 by Christian Franke, 7 years ago

Resolution: fixed
Status: acceptedclosed

Suggested changes applied to all man pages in r4426, r4427.

To avoid problems with older non-groff formatters, \(aq is only used if groff is detected. Otherwise ' is used. Interestingly mandoc also returns true for \n(.g (and supports \(aq).

Note: See TracTickets for help on using tickets.