Ingo Luetkebohle wrote:
> Where can I find a troff macro description for manpages? AFAIK, it does not
> use me, mm or one of the others but rather "mandoc".
It uses the 'an' macro package. Appended is a script I wrote a LONG time
ago to write man pages. It almost certainly needs some minor tweaking to
fit on modern Unix/Linux systems, but should mostly still work. I also
embedded some discussion of the man package.
If it doesn't come through in readable/workable format, E-mail me and I'll
send it as an attachment or a gzip/uuencoded file.
Cheers,
--
Dave Ihnat
[EMAIL PROTECTED]
=========================== Cut here ========================
#
# makeman - an aid to manual page creation
#
# David M. Ihnat
#
# Copyright abandoned 1989
#####
# Environment
#####
set -A DUMBTEST A B 2>/dev/null
if [ $? -ne 0 ]
then
OLDKSH=y;
else
OLDKSH="";
fi;
#####
# Data
#####
HEAD="Bell Laboratories"; 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]=1M
MANSECTLIST[2]=2
MANSECTLIST[3]=3
MANSECTLIST[4]=3C
MANSECTLIST[5]=3F
MANSECTLIST[6]=3M
MANSECTLIST[7]=3S
MANSECTLIST[8]=3N
MANSECTLIST[9]=3X
MANSECTLIST[10]=4
MANSECTLIST[11]=5
MANSECTLIST[12]=6
MANSECTLIST[13]=7
MANSECTLIST[14]=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 \
1M \
2 \
3 \
3C \
3F \
3M \
3S \
3N \
3X \
4 \
5 \
6 \
7 \
8
fi;
DEFEDITOR=vi
DEFPAGER=pg
DEFSPELL=spell
MANNAME="";
SECNNAME=""
FINAL=/usr/tmp/$$.f;
TMPDIR=/usr/tmp
HLEVEL=test
#####
# Functions
#####
Usage()
{
echo "usage: $0 commandname [manual section name]";
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()
{
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 <<!
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()
{
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()
{
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
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()
{
cat <<! | $PAGER
Common nroff/troff/ditroff constructs that are useful are:
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.)
.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.
.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
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.
!
}
#####
# Procedure
#####
if [ ! "$EDITOR" ]
then
EDITOR="$DEFEDITOR"
fi;
if [ ! "$PAGER" ]
then
PAGER=$DEFPAGER;
export PAGER;
fi;
if [ $# -lt 1 ]
then
Usage;
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 "\nEnter 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 \"$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 \"$DEFSPELL\" on $MANNAME.$SECNNAME.mp:"
$DEFSPELL $MANNAME.$SECNNAME.mp | $PAGER
echo "formatted \"man\" page follows:"
nroff -Ttn300 -man $FINAL | col | $PAGER
==================================== END ========================
--
To unsubscribe:
mail -s unsubscribe [EMAIL PROTECTED] < /dev/null
