manpage improvements from Debian package

[Jonathan Dowland]

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.

[Jonathan Dowland]

patch

[Christian Franke]

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 ...

[Alex Samorukov]

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.

[Christian Franke]

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​.

[Christian Franke]

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).