[request-tracker-maintainers] Bug#488609: Include docstrings in manpage.

[Trent W. Buck]

Package: rt3.6-clients
Version: 3.6.6-4
Severity: wishlist
Tags: patch

The manpage for rt(1) doesn't describe any of the subcommands.
Instead this information has to be extracted with "rt help
<subcommand>".  This is counter-intuitive, especially since both sets
of documentation are stored in the rt perl script itself.  The
attached script demonstrates a quick-and-dirty way to insert this
information into the manpage.  I wish something like this would be
done in debian/rules, so that "man rt" included subcommand
documentation.

    #!/bin/sh -e
    {
        ## insert start of existing manpage
        zcat /usr/share/man/man1/rt-3.6.1.gz |
        sed -n 1,/.SH.*AUTHOR/p | sed \$d

        sed -n '/__DATA__/,$ p' /usr/bin/rt-3.6 |
        sed -r \
            -e '1c.SH "COMMANDS"' \
            -e '1a.IX Header "COMMANDS"' \
            -e 's/^Title:/.TP\n.B/' \
            -e '/^(Text:|--)/d'

        ## insert end of existing manpage
        zcat /usr/share/man/man1/rt-3.6.1.gz |
        sed -n /.SH.*AUTHOR/,\$p

    } >rt.man

    man -l rt.man

PS: I home to clean up this script a little in subsequent posts, but
I'll probably get distracted.

-- System Information:
Debian Release: lenny/sid
  APT prefers testing
  APT policy: (990, 'testing')
Architecture: i386 (i686)

Kernel: Linux 2.6.25-2-686 (SMP w/1 CPU core)
Locale: LANG=en_AU.utf8, LC_CTYPE=en_AU.utf8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

Versions of packages rt3.6-clients depends on:
ii  libhtml-format-perl           2.04-2     format HTML syntax trees into text
ii  libhtml-tree-perl             3.23-1     represent and create HTML syntax t
ii  libterm-readkey-perl          2.30-4     A perl module for simple terminal
ii  libterm-readline-perl-perl    1.0302-1   Perl implementation of Readline li
ii  libwww-perl                   5.812-1    WWW client/server library for Perl
ii  msmtp-mta [mail-transport-age 1.4.13-1   light SMTP client with support for
ii  perl                          5.10.0-11  Larry Wall's Practical Extraction

Versions of packages rt3.6-clients recommends:
ii  libio-socket-ssl-perl         1.13-1     Perl module implementing object or

-- no debconf information