I'd feel guilty if I let a release cycle go by without making at least
one contribution.
I use 'man mh-chart' pretty often when I'm trying to remember the name
of a seldom-used command. The other day I couldn't remember the name
of the mh-format man page, and was surprised when mh-chart didn't
have all of the section 5 and 7 nmh pages listed.
I could have just added their names to "SEE ALSO", but that wouldn't
have gotten me descriptions, which is sort of the point of mh-chart.
So I have a patch to mh-chart-gen.sh which auto-generates the SEE ALSO
section. The results look like this (bolding removed for email).
SEE ALSO
mh-alias(5)
format of nmh email-address alias files
mh-draft(5)
draft folder facility for nmh message system
mh-folders(5)
storage format used by nmh message system
mh-format(5)
formatting language for nmh message system
mh-mail(5)
message format for nmh message system
mh-profile, mh_profile(5)
user customization for nmh message handler
mh-sequence(5)
sequence specification for nmh message system
mh-tailor, mts.conf(5)
mail transport configuration for nmh message handler
mh-mime(7)
overview of nmh MIME message composition and display
nmh(7)
overview of the new MH message system
I believe my script changes are "old shell" compatible, if not
"ancient shell" compatible. I get the same output if I run it with
either "bash --posix" or "ash".
I'll attach the new script. I'm happy to tweak it, but I might prefer
doing it after the initial copy is in git.
In addition to the changes to mh-chart-gen.sh itself, there were three
small changes to man pages to make mh-chart look and work a little
better:
- added "overview of the" to the description in nmh(7)
- added "mh_profile" as a synonym name in mh-profile(5)/mh_profile(5)
- changed "mh\-mime" to "mh-mime" in the NAME block of mh-mime(7).
None of the other mh-* man pages have that hyphen, and my
script changes were doubling it up.
paul
=----------------------
paul fox, p...@foxharp.boston.ma.us (arlington, ma, where it's 59.9 degrees)
#!/bin/sh
#
# Generates mh-chart.man from other .man files that have a SYNOPSIS
# section.
#
# This code is Copyright (c) 2012, by the authors of nmh.
# See the COPYRIGHT file in the root directory of the nmh
# distribution for complete copyright information.
nmhmandir=`dirname $0`
# The following ensures the generated date field in the manpage is divorced
# from the local build environment when building distribution packages.
LC_TIME=C; export LC_TIME
unset LANG
datestamp=`date +%Y-%m-%d`
cat <<__HOOPY_FROOD
.TH MH-CHART %manext7% "${datestamp}" "%nmhversion%"
.
.\" %nmhwarning%
.
.SH NAME
mh-chart \- chart of nmh commands and their options
.SH SYNOPSIS
.na
__HOOPY_FROOD
for i in $nmhmandir/*.man; do
case $i in
*/mh-chart.man) ;;
*) if grep '^\.SH SYNOPSIS' "$i" >/dev/null; then
#### Extract lines from just after .SH SYNOPSIS to just before .ad.
#### Filter out the "typical usage:" section in pick.man.
awk '/.SH SYNOPSIS/,/^(\.ad|typical usage:)/ {
if ($0 !~ /^(\.SH SYNOPSIS|\.na|\.ad|typical usage:)/) print
}' "$i"
echo
elif sed 1p $i | grep '^\.so man' >/dev/null
then
: skip one-line pages that just include others
else
# pages without SYNOPSIS are section 5 and 7
see_also="$see_also $i"
fi ;;
esac
done
echo '.SH "SEE ALSO"'
for i in $see_also
do
# extract the section number from the first (.TH) line
section=`sed -n '1s/.*manext\([1-7]\).*/\1/p' $i`
# get the name and description.
name_desc=`grep -A1 '^\.SH NAME' "$i" | grep -v '^\.SH NAME'`
# isolate the name(s) (note: some pages (mh_tailor/mts.conf) have
# two names, so everything up to the \- is name(s)
name=`echo $name_desc | sed -n 's/\(.*\) \\\\-.*/\1/p'`
# escape spaces and hyphens, since this will come after .IR
name=`echo $name | sed 's/[- ]/\\\\&/g'`
# everything after the \- is description
desc=`echo $name_desc | sed -n 's/.*\\\\- \(.*\)/\1/p'`
# sort first by section, then by name
echo "$section.IR $name ($section)XYZZY$desc"
done | sort | sed -e 's/^[1-7]//' -e 's/XYZZY\(.*\)/\
.RS\
\1\
.RE/'
