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
        [EMAIL PROTECTED]
============================ 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.


-- 
To unsubscribe: mail [EMAIL PROTECTED] with "unsubscribe"
as the Subject.

Reply via email to