Lots of warnings and errors with groff for the man pages

Bug #1210114 reported by Thomas Goirand
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
OpenStack Object Storage (swift)
Low
Tobias Stevenson

Bug Description

Hi,

The swift package has a lot of Lintian warnings about man pages, it would be nice if these were fixed (especially the non manpage missing ones).

I: swift: hyphen-used-as-minus-sign usr/share/man/man1/swift-orphans.1.gz:28
N:
N: This manual page seems to contain a hyphen where a minus sign was
N: intended. By default, "-" chars are interpreted as hyphens (U+2010) by
N: groff, not as minus signs (U+002D). Since options to programs use minus
N: signs (U+002D), this means for example in UTF-8 locales that you cannot
N: cut and paste options, nor search for them easily. The Debian groff
N: package currently forces "-" to be interpreted as a minus sign due to
N: the number of manual pages with this problem, but this is a
N: Debian-specific modification and hopefully eventually can be removed.
N:
N: "-" must be escaped ("\-") to be interpreted as minus. If you really
N: intend a hyphen (normally you don't), write it as "\(hy" to emphasise
N: that fact. See groff(7) and especially groff_char(7) for details, and
N: also the thread starting with
N: http://lists.debian.org/debian-devel/2003/debian-devel-200303/msg01481.h
N: tml
N:
N: If you use some tool that converts your documentation to groff format,
N: this tag may indicate a bug in the tool. Some tools convert dashes of
N: any kind to hyphens. The safe way of converting dashes is to convert
N: them to "\-".
N:
N: Because this error can occur very often, Lintian shows only the first 10
N: occurrences for each man page and give the number of suppressed
N: occurrences. If you want to see all warnings, run Lintian with the
N: -d/--debug option.
N:
N: Refer to /usr/share/doc/groff-base/README.Debian and the groff_char(7)
N: manual page for details.
N:
N: Severity: wishlist, Certainty: possible
N:
N: Check: manpages, Type: binary
N:
I: swift: hyphen-used-as-minus-sign usr/share/man/man1/swift-orphans.1.gz:34
I: swift: hyphen-used-as-minus-sign usr/share/man/man1/swift-orphans.1.gz:41
W: swift: binary-without-manpage usr/bin/swift-bench-client
W: swift: binary-without-manpage usr/bin/swift-form-signature
W: swift: binary-without-manpage usr/bin/swift-oldies
W: swift: binary-without-manpage usr/bin/swift-recon
W: swift: binary-without-manpage usr/bin/swift-temp-url
I: swift-container: hyphen-used-as-minus-sign usr/share/man/man1/swift-container-auditor.1.gz:28
I: swift-container: hyphen-used-as-minus-sign usr/share/man/man1/swift-container-replicator.1.gz:28
I: swift-container: hyphen-used-as-minus-sign usr/share/man/man1/swift-container-server.1.gz:28
I: swift-container: hyphen-used-as-minus-sign usr/share/man/man1/swift-container-sync.1.gz:28
I: swift-container: hyphen-used-as-minus-sign usr/share/man/man1/swift-container-updater.1.gz:28
W: swift-container: manpage-has-errors-from-man usr/share/man/man5/container-server.conf.5.gz 218: warning: numeric expression expected (got `)')
N:
N: This man page provokes warnings or errors from man.
N:
N: "cannot adjust" or "can't break" are trouble with paragraph filling,
N: usually related to long lines. Adjustment can be helped by left
N: justifying, breaks can be helped with hyphenation, see "Manipulating
N: Filling and Adjusting" and "Manipulating Hyphenation" in the manual.
N:
N: "can't find numbered character" usually means latin1 etc in the input,
N: and this warning indicates characters will be missing from the output.
N: You can change to escapes like \[:a] described on the groff_char man
N: page.
N:
N: Other warnings are often formatting typos, like missing quotes around a
N: string argument to .IP. These are likely to result in lost or malformed
N: output. See the groff_man (or groff_mdoc if using mdoc) man page for
N: information on macros.
N:
N: This test uses man's --warnings option to enable groff warnings that
N: catch common mistakes, such as putting . or ' characters at the start of
N: a line when they are intended as literal text rather than groff
N: commands. This can be fixed either by reformatting the paragraph so that
N: these characters are not at the start of a line, or by adding a
N: zero-width space (\&) immediately before them.
N:
N: At worst, warning messages can be disabled with the .warn directive, see
N: "Debugging" in the groff manual.
N:
N: Lintian also stricter in regards to declaring manpage preprocessors.
N:
N: To test this for yourself you can use the following command:
N: LC_ALL=en_US.UTF-8 MANROFFSEQ='' MANWIDTH=80 \
N: man --warnings -E UTF-8 -l -Tutf8 -Z <file> >/dev/null
N:
N: Severity: normal, Certainty: certain
N:
N: Check: manpages, Type: binary
N:
I: swift-account: hyphen-used-as-minus-sign usr/share/man/man1/swift-account-auditor.1.gz:28
I: swift-account: hyphen-used-as-minus-sign usr/share/man/man1/swift-account-reaper.1.gz:28
I: swift-account: hyphen-used-as-minus-sign usr/share/man/man1/swift-account-replicator.1.gz:28
I: swift-account: hyphen-used-as-minus-sign usr/share/man/man1/swift-account-server.1.gz:28
I: swift-object: hyphen-used-as-minus-sign usr/share/man/man1/swift-object-auditor.1.gz:28
I: swift-object: hyphen-used-as-minus-sign usr/share/man/man1/swift-object-expirer.1.gz:28
I: swift-object: hyphen-used-as-minus-sign usr/share/man/man1/swift-object-server.1.gz:28
I: swift-object: hyphen-used-as-minus-sign usr/share/man/man1/swift-object-updater.1.gz:28
W: swift-object: manpage-has-errors-from-man usr/share/man/man1/swift-recon.1.gz 87: warning [p 2, 2.2i, div `an-div', 0.0i]: can't break line
I: swift-object: hyphen-used-as-minus-sign usr/share/man/man1/swift-recon.1.gz:28
I: swift-object: hyphen-used-as-minus-sign usr/share/man/man1/swift-recon.1.gz:72
W: swift-object: manpage-has-errors-from-man usr/share/man/man5/object-server.conf.5.gz 228: warning: numeric expression expected (got `)')
W: swift-object: binary-without-manpage usr/bin/swift-recon-cron
I: swift-proxy: hyphen-used-as-minus-sign usr/share/man/man1/swift-proxy-server.1.gz:28
W: swift-proxy: manpage-has-errors-from-man usr/share/man/man5/proxy-server.conf.5.gz 465: warning: numeric expression expected (got `)')

Changed in swift:
importance: Undecided → Low
status: New → Triaged
Changed in swift:
assignee: nobody → Tobias Stevenson (tstevenson)
Changed in swift:
status: Triaged → In Progress
Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to swift (master)

Reviewed: https://review.openstack.org/43949
Committed: http://github.com/openstack/swift/commit/83a6ec1683fa0824d82a889046132a7ac33463a8
Submitter: Jenkins
Branch: master

commit 83a6ec1683fa0824d82a889046132a7ac33463a8
Author: Tobias Stevenson <email address hidden>
Date: Tue Aug 27 16:03:58 2013 -0500

    Man page lintian errors and warnings

    Used groff to recreate the errors. I believe all the issues
    except `binary-without-manpage` are solved. Would like
    confirmation from someone using Lintian.

    Closes-Bug: #1210114
    Change-Id: I533205c53efdb7cdf3645cc3e3dc487f9ee5640a

Changed in swift:
status: In Progress → Fix Committed
Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix proposed to swift (feature/ec)

Fix proposed to branch: feature/ec
Review: https://review.openstack.org/48990

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to swift (feature/ec)
Download full text (17.5 KiB)

Reviewed: https://review.openstack.org/48990
Committed: http://github.com/openstack/swift/commit/175a837befd57b520e28623f0d708d883c023532
Submitter: Jenkins
Branch: feature/ec

commit 4c4a8abaa500d0d3940d81a4eb5ac21215ddc07a
Author: Kun Huang <email address hidden>
Date: Fri Sep 27 15:25:53 2013 +0800

    improve bulk document

    This a very small change which just tell users request url of bulk
    delete request. In original docstrings, it just states the request
    parameters, request body and request method but not request url.

    Change-Id: I0bbc302a0e072910bb58e4814614d7f761433b10

commit df39602c41605c4c68a47c6532a466ccc1a6633d
Author: David Goetz <email address hidden>
Date: Thu Sep 12 07:38:23 2013 -0700

    bulk delete bug with trailing whitespace

    Change-Id: Ia48224a1a187a8ed6b0c9a3c72cac06f084a6fc8

commit d8e0492ea80adae990f35930465d6e905a3be061
Author: Samuel Merritt <email address hidden>
Date: Tue Aug 27 18:00:04 2013 -0700

    Fix internal swift.source tracking.

    In 1.8.0 (Grizzly), your proxy logs would indicate which middleware
    was responsible for an internal request, e.g. TU for tempurl or BD for
    bulk delete. At some point, those all turned into GET_INFO, which does
    not give you any idea which specific middleware was responsible, only
    that it came from a get_account_info/get_container_info call.

    This commit puts it back to how it was in 1.8.0. Also, the
    new-since-1.8.0 function get_object_info() got swift_source plumbing
    added to it, so source tracking for the quota middlewares'
    get_object_info() calls will happen now too.

    Note that due to the new-since-1.8.0 in-environment caching of
    account/container info, you may not see as many lines in the proxy log
    as you would with 1.8.0. This is because there are actually fewer
    internal requests being made.

    Change-Id: I2b2ff7823c612dc7ed7f268da979c4500bbbe911

commit d9d7b2135a7020cdf43172ea4fcf0b1020f49101
Author: Samuel Merritt <email address hidden>
Date: Tue Sep 24 16:43:33 2013 -0700

    Install libffi-dev in SAIO docs.

    If you don't, then newer versions of xattr won't install, and since
    our xattr requirement is simply ">= 0.4" in requirements.txt, this
    affects anyone setting up a new SAIO.

    This happened with xattr 0.7, which was released on 2013-07-19.

    Change-Id: Iaf335fa25a2908953d1fd218158ebedf5d01cc27

commit ce5e810fed8c453f4cd41c3c32162f47cde48f10
Author: Samuel Merritt <email address hidden>
Date: Tue Sep 24 16:20:28 2013 -0700

    Update SAIO doc to have double proxy-logging in pipeline.

    Change-Id: I0a034ca1420761cbf4e35dcea1d9cd18a92f90bd

commit 3e6f9293b8882cecb151e87fe5bfbe24e605b847
Author: Brian D. Burns <email address hidden>
Date: Thu Aug 1 14:50:03 2013 -0400

    update SLO delete error handling

    * ensure all responses are 200 OK
    * report missing sub-SLO manifests or other error messages in bulk
      delete response

    Change-Id: Iaf88c94bc7114ff3c9751f9f31f8f748de911f8a

commit 92ae497800d9e66795346019cf284026a751597e
Author: ZhiQiang Fan <email address hidden>
Date: Fri Sep 20 23:34:06 201...

Thierry Carrez (ttx)
Changed in swift:
milestone: none → 1.10.0-rc1
status: Fix Committed → Fix Released
Thierry Carrez (ttx)
Changed in swift:
milestone: 1.10.0-rc1 → 1.10.0
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers