[Pkg-rust-maintainers] Bug#985804: rust-coreutils manpages cleanup

Daniel Kahn Gillmor dkg at fifthhorseman.net
Wed Mar 24 00:25:03 GMT 2021

Package: rust-coreutils
Version: 0.0.4-1~exp2

Thanks for rust-coreutils.  Very interesting project.

A few thoughts about how to improve the documentation (manual pages in particular):

 - the manpages seem to be generated with help2man.  that's cool, but i
   recommend supplying the --no-info argument to avoid clauses like

       The  full  documentation for tac is maintained as a Texinfo manual.  If
       the info and tac programs are properly installed at your site, the com‐

              info tac

       should give you access to the complete manual.

 - naming the manpage rust-foo is a bit confusing when the contents of
   the manpage refer to "foo".  I'd suggest that a manual subsection
   would be better (e.g. 1rust, by analogy with 1ssl from OpenSSL).
   then the file could be named simply foo.1rust.gz.  Then a user can
   read it with "man 1rust tac" or "man 'tac(1rust)'"

 - The manpage doesn't clearly identify the source as uutils (or "Rust
   coreutils" or whatever), so it's hard when looking at it to see
   what's going on there.

You can resolve this with help2man by invoking it this way (using tac as
an example):

   help2man --source "uutils (Rust) coreutils $VERSION" \
            --section 1rust \
            --no-info \
            --output tac.1rust \


 - the formatting of the --help output isn't quite what help2man wants
   to parse.  In particular, I'm seeing rendered output like this:

       tac - manual page for tac 0.0.4

       tac 0.0.4

              tac [OPTION]... [FILE]...

       Write each file to standard output, last line first.


   Instead, i think you want:

      tac - concatenate and print files in reverse

      tac [OPTION]... [FILE]...

      Write each file to standard output, last line first.


    I don't know how to solve this particular just by fiddling with
    help2man, though In particular: (a) I don't know where to find the
    "concatenate and print files in reverse" string (it's not in the
    --help output), but if you do, you should be able to supply it as
    the "--name" parameter to help2man.  And (b) i'm not sure why
    help2man is confused about the SYNOPSIS section -- it probably
    presumes something about the output format.  For tac it looks like
    it can be fixed directly in src/uu/tac/src/tac.rs, because the
    format-string is distinct from the text produced by GNU tac.

Hopefully these notes are useful.  i considered filing them upstream,
but i noticed that there is no mention of help2man upstream, so i think
the bulk of this needs to be fixed in debian/rules.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 227 bytes
Desc: not available
URL: <http://alioth-lists.debian.net/pipermail/pkg-rust-maintainers/attachments/20210323/fd4a1b5d/attachment.sig>

More information about the Pkg-rust-maintainers mailing list