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
signature.asc
Description: PGP signature
