Committed, again. (Re: improved mh-chart man page)
Dave tactfully pointed out privately that I'd committed the man page changes to the 1.7 release branch, rather than master. Sigh. I've now pushed reverts to 1.7-release, and cherry-picked my 4 commits onto master. Sorry for the git-noise. :-/ paul =-- paul fox, p...@foxharp.boston.ma.us (arlington, ma, where it's 39.7 degrees)
Re: improved mh-chart man page
Paul wrote: > I'm fine with not relying on GNU-isms, and I think we should avoid > the cutting edge in general, but in this case, I think we can take > a step forward. If we get complaints, I'll be happy to revert to > backticks. Sounds like a plan. David
Re: improved mh-chart man page
ken wrote: > >I vote to stay with backticks. We've maintained (or at least tried to > >maintain) Bourne shell throughout the rest of nmh, and I think we > >should keep it that way. > > Officially, $(...) is part of POSIX; it's not a Bash-ism. > > https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html And, in fact, it was part of the POSIX.2 standard of 1994, 27 years ago: https://pubs.opengroup.org/onlinepubs/009656399/toc.pdf (p.36) > > We USED to use $(...) in the test suite. But that was dropped because > it turns out that /bin/sh on Solaris does not support that (at least, that > was my memory). I am neutral about whether or not we should continue > to support ancient shells. I suspect anyone still running Solaris has long ago figured out how to deal with "modern" shell features creeping into their ecosystem. But how old, exactly, does a Solaris system need to be to not be running a POSIX compliant shell? I'm fine with not relying on GNU-isms, and I think we should avoid the cutting edge in general, but in this case, I think we can take a step forward. If we get complaints, I'll be happy to revert to backticks. paul =-- paul fox, p...@foxharp.boston.ma.us (arlington, ma, where it's 55.0 degrees)
Re: improved mh-chart man page
On Tue, 23 Mar 2021 16:09:38 -0400, Ken Hornstein said: > We USED to use $(...) in the test suite. But that was dropped because > it turns out that /bin/sh on Solaris does not support that (at least, that > was my memory). I am neutral about whether or not we should continue > to support ancient shells. The question becomes: How many users are (a) on Solaris that old *and* (b) likely to update to nhm 1.7.1? And is there anything we can to do help them migrate off ancient Solaris to semi-this-century Solaris? pgprXews0qd9u.pgp Description: PGP signature
Re: improved mh-chart man page
>I vote to stay with backticks. We've maintained (or at least tried to >maintain) Bourne shell throughout the rest of nmh, and I think we >should keep it that way. Officially, $(...) is part of POSIX; it's not a Bash-ism. https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html We USED to use $(...) in the test suite. But that was dropped because it turns out that /bin/sh on Solaris does not support that (at least, that was my memory). I am neutral about whether or not we should continue to support ancient shells. --Ken
Re: improved mh-chart man page
Paul wrote: > I only used the backticks because they'd already > been used in that script, and I couldn't remember how strict we were > being about our build environment. I vote to stay with backticks. We've maintained (or at least tried to maintain) Bourne shell throughout the rest of nmh, and I think we should keep it that way. David
Re: improved mh-chart man page
john wrote: > On 3/23/2021 5:26 PM, Robert Elz wrote: > > Date:Tue, 23 Mar 2021 08:28:24 -0400 > > From:Paul Fox > > Message-ID: <20210323122824.e92ca5180...@grass.foxharp.boston.ma.us> > > > >| Are we allowed to use $(...) instead of `...` ? > > > > I would. I cannot imagine any shell anyone is likely to really use > > which doesn't support that. > > > > $() is less prone to errors (1, Command Substitution). Excellent. Thanks. I only used the backticks because they'd already been used in that script, and I couldn't remember how strict we were being about our build environment. I'll change them all to $(...). I haven't personally used a backtick in my own scripts for... decades? I'd actually forgotten the baroque behavior of backlash quoting. And echo --> printf. Again, I was nervous about introducing it. paul =-- paul fox, p...@foxharp.boston.ma.us (arlington, ma, where it's 57.2 degrees)
Re: improved mh-chart man page
On 3/23/2021 5:26 PM, Robert Elz wrote: Date:Tue, 23 Mar 2021 08:28:24 -0400 From:Paul Fox Message-ID: <20210323122824.e92ca5180...@grass.foxharp.boston.ma.us> | Are we allowed to use $(...) instead of `...` ? I would. I cannot imagine any shell anyone is likely to really use which doesn't support that. $() is less prone to errors (1, Command Substitution). I'd also use printf instead of echo - even if the shell doesn't have printf built in (possible, if unlikely) the command will exist. echo is just too bizarre on some systems (especially since *roff input is a place where \ characters abound, and those are how you can shoot yourself with echo). And quote expansions almost always, no matter how safe you believe they are. These latter two probably don't matter for the current nmh man page set, but for the future, who knows. +1 1) https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xcu_chap02.html -- John Doe
Re: improved mh-chart man page
Date:Tue, 23 Mar 2021 08:28:24 -0400 From:Paul Fox Message-ID: <20210323122824.e92ca5180...@grass.foxharp.boston.ma.us> | Are we allowed to use $(...) instead of `...` ? I would. I cannot imagine any shell anyone is likely to really use which doesn't support that. I'd also use printf instead of echo - even if the shell doesn't have printf built in (possible, if unlikely) the command will exist. echo is just too bizarre on some systems (especially since *roff input is a place where \ characters abound, and those are how you can shoot yourself with echo). And quote expansions almost always, no matter how safe you believe they are. These latter two probably don't matter for the current nmh man page set, but for the future, who knows. kre
Re: improved mh-chart man page
david wrote:
> Paul wrote:
> > 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".
>
> grep -A is a GNU-ism. Maybe something like sed -n '/.SH NAME/{n;p;}'
> would simplify that whole line?
>
Thanks. Much better. I think I only finally internalized how to
introduce newlines in the output with sed a year or two ago. If I
master function groups now, maybe there's hope for someday being able
to use the hold space without visiting one of the sed cheat sheet
sites! (Kind of embarrassing for a guy who first used sed over 40
years ago.)
Are we allowed to use $(...) instead of `...` ? I hate working around
the deficiencies of `...`.
paul
=--
paul fox, p...@foxharp.boston.ma.us (arlington, ma, where it's 35.8 degrees)
Re: improved mh-chart man page
Paul wrote:
> 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).
Good stuff.
> 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".
grep -A is a GNU-ism. Maybe something like sed -n '/.SH NAME/{n;p;}'
would simplify that whole line?
David
improved mh-chart man page
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/'
