Re: makeman utility--anyone want it?

[ignatz dminet com (Dave Ihnat)]

Gustav Schaffter wrote:

> Is it available for download somewhere? :-)

No.  With a couple of minor changes that I'd like to get out for the Linux
crowd, and as short as it is...  If it gets mangled in any way, I'll send
it to individuals (and resend to those who ask.)

If I get time later today, I'll stick it on my web page.
-- 
	Dave Ihnat
	ignatz dminet com
============================ HIER SCHNEIDEN =============================
#!/bin/ksh
#
# makeman - an aid to manual page creation
#
# David M. Ihnat
#
# Copyright abandoned 1989
#####
# Environment
#####
VERSION="2.0";

set -A DUMBTEST A B 2>/dev/null
if [ $? -ne 0 ]
then
	OLDKSH=y;
else
	OLDKSH="";
fi;

#####
# Data
#####

HEAD="Dave Ihnat's Systems"; export HEAD;

if [ "$OLDKSH" ]
then
	SECTLIST[0]=SYNOPSIS
	SECTLIST[1]=DESCRIPTION
	SECTLIST[2]=EXAMPLES
	SECTLIST[3]=FILES
	SECTLIST[4]="SEE_ALSO"
	SECTLIST[5]=DIAGNOSTICS
	SECTLIST[6]=NOTES
	
	TMPFILES[0]=SYN
	TMPFILES[1]=DESC
	TMPFILES[2]=EX
	TMPFILES[3]=FI
	TMPFILES[4]=ALSO
	TMPFILES[5]=DIAG
	TMPFILES[6]=NOTE

	MANSECTLIST[0]=1
	MANSECTLIST[1]=1L
	MANSECTLIST[2]=1M
	MANSECTLIST[3]=2
	MANSECTLIST[4]=3
	MANSECTLIST[5]=3C
	MANSECTLIST[6]=3F
	MANSECTLIST[7]=3M
	MANSECTLIST[8]=3S
	MANSECTLIST[9]=3N
	MANSECTLIST[10]=3X
	MANSECTLIST[11]=4
	MANSECTLIST[12]=5
	MANSECTLIST[13]=6
	MANSECTLIST[14]=7
	MANSECTLIST[15]=8
else
	set -A SECTLIST \
		SYNOPSIS \
		DESCRIPTION \
		EXAMPLES \
		FILES \
		"SEE_ALSO" \
		DIAGNOSTICS \
		NOTES
	
	set -A TMPFILES \
		SYN \
		DESC \
		EX \
		FI \
		ALSO \
		DIAG \
		NOTE

	set -A MANSECTLIST \
		1 \
		1L \
		1M \
		2 \
		3 \
		3C \
		3F \
		3M \
		3S \
		3N \
		3X \
		4 \
		5 \
		6 \
		7 \
		8 
fi;

DEFEDITOR=vi
DEFPAGER=pg

# If on Linux, this should be ispell and don't page.
#DEFSPELL=spell
#SPELLPAGE=Y

DEFSPELL=ispell
SPELLPAGE="";

MANNAME="";
SECNNAME=""

FINAL=/usr/tmp/$$.f;
TMPDIR=/usr/tmp

HLEVEL=test
#####
# Functions
#####
Usage()
{
	echo "usage: $0 commandname [manual section name]";
	echo "       $0 -p";
	echo "       $0 -?";
	echo "";
	echo "The -p option prints detailed help to the default system printer.";
	echo "The -? option prints this usage.";
	exit 1
}

Yesno()
{
	read ANS?"$1: ";

	case "$ANS" in
	y|Y|yes|YES|Yes)
		return 1;
		;;

	n|N|no|NO|No)
		return 0;
		;;

	*)
		echo "Answer y or n!";
		sleep 1;
	esac;
}

Help()
{
	if [ "$1" = "Print" ]
	then
		Scnhelp $1;
		Manscnhelp $1;
		Fmthelp $1;

		return;
	fi;

	PS3="Choice (return to redisplay help list)=> "
	select ITEM in SECTIONS "Manual Sections" "MP Formatting" "return from help"
	do
		case $ITEM in
		SECTIONS)
			Scnhelp;
			;;

		"Manual Sections")
			Manscnhelp;
			;;

		"MP Formatting")
			cat <<! | fmt
By and large, man page formatting relies on standard nroff/troff/ditroff
constructs.  The most common mistake is using Memorandum Macros; the set
invoked by the '-man' option is different, although there is some overlapping
functionality.  It isn't necessary to know any formatting macros or
conventions, however--simply typing text will get it formatted, unless you
stumble on some embedded command sequence.

Although this command can't teach {n|t|dit}roff programming, a brief
overview of commonly useful constructs, and specific man macros, is available.

!
		Yesno "Would you like to see this?"
		if [ $? -ne 0 ]
		then
			Fmthelp;
		fi;
			;;

		"return from help")
			return;
			;;

		esac;
	done
}

Scnhelp()
{
	if [ "$1" = "Print" ]
	then
		PAGER=lp;
	fi;

	cat <<! | $PAGER
Sections refer to the major component headings seen in Unix manual pages.
No section is mandatory, although a manual with no sections is a nice exercise
in futility.  You may create and subsequently modify any section in any order;
they will be rearranged to reflect the traditional ordering.

Sections are:
SYNOPSIS:
	This section describes detailed options, syntax, and parameters.
	It is common to embolden standard command elements and invariant
	options, leaving paramters in either normal font, or in italics, e.g.,
		\fBcommand \fB[-x [\fP\fIlist\fP\fB]\fP
	
	(Yes, this can get ugly.)

DESCRIPTION:
	This section provides the fully detailed description of the topic.
	It is in free-form, although man page formatting macros may be, and
	probably should, be used to provide visual cues such as hanging
	indents.

EXAMPLES:
	Specific examples may be provided, particularly to clarify usage
	for complex commands.

FILES:
	Any devices, files, or directories used by this command should be
	delimited here.  Don't forget to put troff '.br' commands between
	elements.

SEE ALSO:
	It's particularly useful and friendly to mention any other man pages
	that directly relate to this one.

DIAGNOSTICS:
	Description of not only informational and error messages that may
	appear on stdout and stderr, but also exit codes.

NOTES:
	This section subsumes the colloquial (but more colorful) sections
	seen in simpler days, such as CAVEATS, WARNINGS, and BUGS.  Simply
	put, anything of special interest to the user or developer should
	be noted here--dangerous side effects, known aberrations, easily
	overlooked usages, etc.
!
}

Manscnhelp()
{
	if [ "$1" = "Print" ]
	then
		PAGER=lp;
	fi;

	cat <<! | $PAGER

Manual pages traditionally belong in one of a defined set of manual set
sections (not to be confused with SECTIONS within a manual page.)  As of
System V Release 4, these are as defined below; some may not apply to a
particular release or version of Unix.  Feel free to substitute
a section number or description which better describes your site or version
of Unix and its documentation if necessary, however.

Section		Contents
-----------------------------------------------------------------------------
1		General Commands
1M		Administrative Commands
1L              Local Commands (General)
2		Kernel Requests (System Calls)
3		General Library; also '3C' on some systems
3C		Standard C library 'libc'
3F		Standard Fortran Library 'libF77'
3M		Math Library Routines 'libm'
3S		Standard I/O Library (stdio); in 'libc'
3N		Network Services Library; variously 'libnsl', 'lbsd', 'lsun'
3X		Varous Specialized Libraries
4		File Formats
5		Miscellany
6		Games
7		Special Files and Networking Facilities
8 		Specialized System Procedures and Commands

!

}

Fmthelp()
{
	if [ "$1" = "Print" ]
	then
		PAGER=lp;
	fi;

	cat <<! | $PAGER

Common nroff/troff/ditroff constructs that are useful follow.  Those
that typically only have an effect under 'troff' are marked with [T];
those that may not be in all packages are marked as optional [O].  If
it's optional, test it before using it!

BOLD/ITALIC:
	Bracket text with '\fB' to turn on bold, '\fI' for italic;
	close the affected text with '\fP' to return to the previous font.
	See the custom man package bold and italic commands as well.

BREAKS:
	To force a line break, a single line starting in the first
	character position and consisting of the string '.br' will do
	the job.

Specific man macros follow.  Please note this isn't a comprehensive list;
it consists only of those commands most commonly useful while editing
sections.  For a detailed and complete description, see man(5).

.B text
	Make 'text' bold.  Only that text on the current input line is
	affected.

.I text
	Make 'text' italic.  Only that text on the current input line is
	affected.

.SM text
	Make 'text' 1 point smaller than the default size.  Only that text
	on the current input line is affected. (Only if output device can
	support it.) [T]

.P
.PP
	Begin a paragraph with normal font, point size, and indent.

.HP in
	Begin paragraph with hanging indent.  Indent is value of 'in'
	(inches for nroff, ems for troff), or the default of 7.2 ens in
	troff or .5" in nroff if omitted.

.TP in
	Begin indented paragraph with hanging tag.  The next line that
	contains text to be printed is taken as the tag.  If the tag doesn't
	fit, it's printed on a separate line.  The indent is as for .HP.
	(Often used in command option lists in the DESCRIPTION section.)

.IP t in
	Same as .TP with tag 't'; often used to get an indented paragraph
	without a tag.

.RS in
	Increase relative indent (initially zero.)  All output is indented
	an additional 'in' units from the current left margin.

.RE k
	Return to the 'k'th relative indent level (set by .RS); initial
	'k' is 1 (zero is equivalent.)  If 'k' omitted, drop one level.

.PM m y
	Produces proprietary markings, where 'm' is:
		P	- Proprietary
		RS	- Restricted
		RG	- Registered
		CR	- Copyright	   (y = year, default is current year)
		UW	- Unpublished Work (y = year, default is current year)
		CP	- See Cover Page
	All of these should be considered Optional until tested.  They
	may not have made it out of Bell Labs.

The following strings may be used anywhere in text:

\*R
	"(Reg.)" in nroff, "Registered" symbol in troff.

\*S
	Change to default type size.  Useful if you've used explicit troff
	size change commands (e.g., \s1)

\*(Tm
	Tradmark indicator.[O]
!

}
#####
# Procedure
#####
EDDATE=`date "+%B %d %Y"`;

if [ ! "$EDITOR" ]
then
	EDITOR="$DEFEDITOR"
fi;

if [ ! "$PAGER" ]
then
	PAGER=$DEFPAGER;
	export PAGER;
fi;

if [ $# -lt 1 ]
then
	Usage;
elif [ "$1" = "-?" ]
then
	Usage;
elif [ "$1" = "-p" ]
then
	Help Print;
	exit 0;
else
	MANNAME="$1";
	shift;
fi;

if [ $# -ge 1 ]
then
	SECNNAME="$1";
	shift;
fi;

if [ $# -gt 0 ]
then
	Usage;
fi

echo "TST" >dork$$
if [ ! -s dork$$ ]
then
	echo "Error: cannot create files in current directory"
	exit 1;
else
	rm -f dork$$
fi;

if [ ! "$SECNNAME" ]
then
	PS3="Choice (return to redisplay manual section list)=> "
	select TSECT in ${MANSECTLIST[*]} help "Custom Section"
	do
		case "$TSECT" in
		help)
			Manscnhelp;
			;;

		"Custom Section")
			read SECNNAME?"Please enter the section number/name you wish: "
			echo "You entered \"$SECNNAME\"."
			Yesno "Is this correct?";
			if [ $? -eq 1 ]
			then
				break;
			else
				SECNNAME="";
			fi;
			;;

		*)
			SECNNAME="$TSECT";
			break;
		esac;
	done
fi;
	
if [ -f $MANNAME.$SECNNAME.mp ]
then
	echo "WARNING: this man page will overwrite file $MANNAME.mp"
fi

trap 'rm -f /usr/tmp/$$.*' 0
trap 'exit 4' 1 2 3 15

echo "Current heading: <$HEAD>"
echo "Enter new heading, or return to keep this one:"
read THEAD?">"
if [ "${#THEAD}" != 0 ]
then
	HEAD="$THEAD";
	unset THEAD;
fi;

CAPNAME=`echo $MANNAME | dd conv=ucase 2>/dev/null`

echo ""
echo "Enter one-line abstract of command.  This will be appended to the"
echo "command name and appear under the NAME heading on the output page."

read ABSTRACT?">"

echo ".TH $CAPNAME $SECNNAME \"$EDDATE\" \"$HEAD\"" >> $FINAL
cat >>$FINAL <<!
.SH NAME
$MANNAME \- $ABSTRACT
!

echo ""
echo "You may now select from the valid sections; any or all may be omitted."
echo "Already processed sections are marked with '#'."
echo "Sections will be organized in the proper order when processing is complete."
echo ""

QUITIT="";
if [ ! "$OLDKSH" ]
then
	set -A TSECTLIST ${SECTLIST[*]}
else
	INDEX=0;
	while [ "${SECTLIST[$INDEX]}" != "" ]
	do
		TSECTLIST[$INDEX]="${SECTLIST[$INDEX]}";
		let INDEX=$INDEX+1
	done;
fi;

PS3="Choice (return to redisplay manual page section list)=> "

while [ ! "$QUITIT" ]
do
	PS3="Choice (return to redisplay manual page section list)=> "

	select SECT in ${TSECTLIST[*]} quit help 
	do
		case "$SECT" in
		help)
			Help;
			PS3="Choice (return to redisplay manual page section list)=> "
			;;

		quit)
			QUITIT=y;
			break;
			;;

		*)
			let REPLY=$REPLY-1;

			TMPF=$TMPDIR/$$.${TMPFILES[$REPLY]}
			TSECTLIST[$REPLY]="#${SECTLIST[$REPLY]}"

			if [ ! -s "$TMPF" ]
			then
				echo "You will be placed in the editor to create section $SECT"
				echo "'''Editing section $SECT (Delete this line)" >$TMPF
			else
				echo "You will be placed in the editor to modify section ${SECTLIST[$REPLY]}"
			fi;

			sleep 1;
			$EDITOR $TMPF
			break;
			;;
		esac;
	done
done;

INDEX=0;

for SECF in ${TMPFILES[*]}
do
	TMPF=$TMPDIR/$$.$SECF
	SECT=${SECTLIST[$INDEX]};

	if [ -s $TMPF ]
	then
		echo ".SH $SECT" >> $FINAL
		cat $TMPF  >> $FINAL
	fi;

	let INDEX=$INDEX+1
done;

cat $FINAL >$MANNAME.$SECNNAME.mp

echo "running spell check on $MANNAME.$SECNNAME.mp:"
if [ "$SPELLPAGE" ]
then
	$DEFSPELL $MANNAME.$SECNNAME.mp | $PAGER
else
	$DEFSPELL $MANNAME.$SECNNAME.mp
fi;

echo "formatted \"man\" page follows:"
nroff -Ttn300 -man $FINAL | col | $PAGER
=============================== HIER SCHNEIDEN =============================
.TH MAKEMAN 1L "15 December 1999" "Public Domain"
.SH NAME
makeman \- Create nroff/troff man pages
.SH SYNOPSIS
\fBmakeman\fP commandname [section]
.br
\fBmakeman -p
.br
makeman -?\fP
.SH DESCRIPTION
\fBmakeman\fP is a shell script that walks the user through the process
of creating a manual page suitable for nroff or troff (and by extension
\fIman2html\fP).
.P
Writing n/troff scripts is an arcane art today; however, it's still the
format of choice for man pages on many Unix systems, and especially
Linux.  This command greatly reduces the amount of n/troff knowledge
necessary to produce a manual page--effectively, none is needed if
no special effects are necessary (e.g., \fIitalic\fP or \fBbold\fP
printing, or hanging indents).
.P
The command has help incorporated that provides comprehensive
explanation of the meanings of man page sections and content, as well
as details on the most commonly used n/troff macros used in man pages
to provide more elegant effects.
.P
Two help options are available; if used, they are mutually exclusive,
and in either case the command will provide the requested help and exit.
.TP
.B -?
A simple usage message is printed and the program exits.
.TP
.B -p
All detailed help messages will be printed on the default system printer
and the program exits.
.P
Minimal invocation is to provide a command name on the command line.
The user will then be presented with a menu of available standard
Section numbers, plus a help option or the ability to create a custom
section.  This menu can be circumvented by providing the section on
the command line as well.
.P
Thereafter, \fBmakeman\fP will put the user into a series of
editing sessions for different common man page sections; any section
can be skipped or re-edited during this session.  Help is available
at any time (while not in an editing session).
.P
Once all desired sections are created and/or re-edited, the program
will combine them into a file with the name \fIcommand.scnnum.mp\fP
and run the spell checker.  Thereafter it will attempt to run nroff
and page the result to the screen.
.SH ENVIRONMENT
A couple of common environment variables are used; if not set, the
default values will be assigned for the duration of the session as noted.
.P
.TP
.B EDITOR
Specifies the editor used in section editing sessions.  Defaults to \fIvi\fP.
.TP
.B PAGER
Specifies the pager used, particularly in help.  Defaults to \fIpg\fP.
.SH SEE_ALSO
man(1), man(5), lp(1), spell(1), pg(1)
.SH NOTES
The internal string \fBHEAD\fP is expected to be set to a default for
the location; you probably won't like the default already in place.
.P
The default spell checker is \fIspell\fP, set in the internal string
\fBDEFSPELL\fP.
.P
This is an \fIold\fP script; I put it in the Public Domain many years
ago.  Do with it as you will.  Caveat Utilitor.