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

[Daniel Kahn Gillmor]

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
   this:

---
SEE ALSO
       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‐
       mand

              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 \
            /usr/lib/cargo/bin/coreutils/tac 



Additionally:

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

---
NAME
       tac - manual page for tac 0.0.4

DESCRIPTION
       tac 0.0.4

   Usage:
              tac [OPTION]... [FILE]...

       Write each file to standard output, last line first.

OPTIONS
---

   Instead, i think you want:

---
NAME
      tac - concatenate and print files in reverse

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

DESCRIPTION
      Write each file to standard output, last line first.

OPTIONS
---

    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.

Regards,

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