1 : #!/usr/bin/perl-5.005
2 eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
3 if $running_under_some_shell;
5 $DEF_PM_SECTION = '3pm' || '3';
9 pod2man - translate embedded Perl pod directives into man pages
14 [ B<--section=>I<manext> ]
15 [ B<--release=>I<relpatch> ]
16 [ B<--center=>I<string> ]
17 [ B<--date=>I<string> ]
18 [ B<--fixed=>I<font> ]
25 B<pod2man> converts its input file containing embedded pod directives (see
26 L<perlpod>) into nroff source suitable for viewing with nroff(1) or
27 troff(1) using the man(7) macro set.
29 Besides the obvious pod conversions, B<pod2man> also takes care of
30 func(), func(n), and simple variable references like $foo or @bar so
31 you don't have to use code escapes for them; complex expressions like
32 C<$fred{'stuff'}> will still need to be escaped, though. Other nagging
33 little roffish things that it catches include translating the minus in
34 something like foo-bar, making a long dash--like this--into a real em
35 dash, fixing up "paired quotes", putting a little space after the
36 parens in something like func(), making C++ and PI look right, making
37 double underbars have a little tiny space between them, making ALLCAPS
38 a teeny bit smaller in troff(1), and escaping backslashes so you don't
47 Set the centered header to a specific string. The default is
48 "User Contributed Perl Documentation", unless the C<--official> flag is
49 given, in which case the default is "Perl Programmers Reference Guide".
53 Set the left-hand footer string to this value. By default,
54 the modification date of the input file will be used.
58 The fixed font to use for code refs. Defaults to CW.
62 Set the default header to indicate that this page is of
63 the standard release in case C<--center> is not given.
67 Set the centered footer. By default, this is the current
72 Set the section for the C<.TH> macro. The standard conventions on
73 sections are to use 1 for user commands, 2 for system calls, 3 for
74 functions, 4 for devices, 5 for file formats, 6 for games, 7 for
75 miscellaneous information, and 8 for administrator commands. This works
76 best if you put your Perl man pages in a separate tree, like
77 F</usr/local/perl/man/>. By default, section 1 will be used
78 unless the file ends in F<.pm> in which case section 3 will be selected.
82 Don't complain when required sections aren't present.
86 =head1 Anatomy of a Proper Man Page
88 For those not sure of the proper layout of a man page, here's
89 an example of the skeleton of a proper man page. Head of the
90 major headers should be setout as a C<=head1> directive, and
91 are historically written in the rather startling ALL UPPER CASE
92 format, although this is not mandatory.
93 Minor headers may be included using C<=head2>, and are
94 typically in mixed case.
100 Mandatory section; should be a comma-separated list of programs or
101 functions documented by this podpage, such as:
103 foo, bar - programs to do something
107 A short usage summary for programs and functions, which
108 may someday be deemed mandatory.
112 Long drawn out discussion of the program. It's a good idea to break this
113 up into subsections using the C<=head2> directives, like
115 =head2 A Sample Subection
117 =head2 Yet Another Sample Subection
121 Some people make this separate from the description.
125 What the program or function returns if successful.
129 Exceptions, return codes, exit stati, and errno settings.
133 Give some example uses of the program.
137 Envariables this program might care about.
141 All files used by the program. You should probably use the FE<lt>E<gt>
146 Other man pages to check out, like man(1), man(7), makewhatis(8), or catman(8).
150 Miscellaneous commentary.
154 Things to take special care with; sometimes called WARNINGS.
158 All possible messages the program can print out--and
163 Things that are broken or just don't work quite right.
167 Bugs you don't plan to fix :-)
171 Who wrote it (or AUTHORS if multiple).
175 Programs derived from other sources sometimes have this, or
176 you might keep a modification log here.
182 pod2man program > program.1
183 pod2man some_module.pm > /usr/perl/man/man3/some_module.3
184 pod2man --section=7 note.pod > note.7
188 The following diagnostics are generated by B<pod2man>. Items
189 marked "(W)" are non-fatal, whereas the "(F)" errors will cause
190 B<pod2man> to immediately exit with a non-zero status.
194 =item bad option in paragraph %d of %s: ``%s'' should be [%s]<%s>
196 (W) If you start include an option, you should set it off
197 as bold, italic, or code.
199 =item can't open %s: %s
201 (F) The input file wasn't available for the given reason.
203 =item Improper man page - no dash in NAME header in paragraph %d of %s
205 (W) The NAME header did not have an isolated dash in it. This is
206 considered important.
208 =item Invalid man page - no NAME line in %s
210 (F) You did not include a NAME header, which is essential.
212 =item roff font should be 1 or 2 chars, not `%s' (F)
214 (F) The font specified with the C<--fixed> option was not
215 a one- or two-digit roff font.
217 =item %s is missing required section: %s
219 (W) Required sections include NAME, DESCRIPTION, and if you're
220 using a section starting with a 3, also a SYNOPSIS. Actually,
221 not having a NAME is a fatal.
223 =item Unknown escape: %s in %s
225 (W) An unknown HTML entity (probably for an 8-bit character) was given via
226 a C<EE<lt>E<gt>> directive. Besides amp, lt, gt, and quot, recognized
227 entities are Aacute, aacute, Acirc, acirc, AElig, aelig, Agrave, agrave,
228 Aring, aring, Atilde, atilde, Auml, auml, Ccedil, ccedil, Eacute, eacute,
229 Ecirc, ecirc, Egrave, egrave, ETH, eth, Euml, euml, Iacute, iacute, Icirc,
230 icirc, Igrave, igrave, Iuml, iuml, Ntilde, ntilde, Oacute, oacute, Ocirc,
231 ocirc, Ograve, ograve, Oslash, oslash, Otilde, otilde, Ouml, ouml, szlig,
232 THORN, thorn, Uacute, uacute, Ucirc, ucirc, Ugrave, ugrave, Uuml, uuml,
233 Yacute, yacute, and yuml.
235 =item Unmatched =back
237 (W) You have a C<=back> without a corresponding C<=over>.
239 =item Unrecognized pod directive: %s
241 (W) You specified a pod directive that isn't in the known list of
242 C<=head1>, C<=head2>, C<=item>, C<=over>, C<=back>, or C<=cut>.
249 If you would like to print out a lot of man page continuously, you
250 probably want to set the C and D registers to set contiguous page
251 numbering and even/odd paging, at least on some versions of man(7).
252 Settting the F register will get you some additional experimental
255 troff -man -rC1 -rD1 -rF1 perl.1 perldata.1 perlsyn.1 ...
257 The indexing merely outputs messages via C<.tm> for each
258 major page, section, subsection, item, and any C<XE<lt>E<gt>>
268 The =over and =back directives don't really work right. They
269 take absolute positions instead of offsets, don't nest well, and
270 making people count is suboptimal in any event.
274 Original prototype by Larry Wall, but so massively hacked over by
275 Tom Christiansen such that Larry probably doesn't recognize it anymore.
283 # We try first to get the version number from a local binary, in case we're
284 # running an installed version of Perl to produce documentation from an
285 # uninstalled newer version's pod files.
286 if ($^O
ne 'plan9' and $^O
ne 'dos' and $^O
ne 'os2' and $^O
ne 'MSWin32') {
287 my $perl = (-x
'./perl' && -f
'./perl' ) ?
289 ((-x
'../perl' && -f
'../perl') ?
292 ($version,$patch) = `$perl -e 'print $]'` =~ /^(\d\.\d{3})(\d{2})?/ if $perl;
294 # No luck; we'll just go with the running Perl's version
295 ($version,$patch) = $] =~ /^(.{5})(\d{2})?/ unless $version;
296 $DEF_RELEASE = "perl $version";
297 $DEF_RELEASE .= ", patch $patch" if $patch;
302 my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime($secs);
303 my $mname = (qw{Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
})[$mon];
305 return "$mday/$mname/$year";
311 $DEF_CENTER = "User Contributed Perl Documentation";
312 $STD_CENTER = "Perl Programmers Reference Guide";
317 warn "$0: @_\n" if @_;
319 usage: $0 [options] podpage
321 --section=manext (default "$DEF_SECTION")
322 --release=relpatch (default "$DEF_RELEASE")
323 --center=string (default "$DEF_CENTER")
324 --date=string (default "$DEF_DATE")
325 --fixed=font (default "$DEF_FIXED")
326 --official (default NOT)
331 $uok = GetOptions
( qw(
341 $DEF_DATE = makedate
((stat($ARGV[0]))[9] || time());
343 usage
("Usage error!") unless $uok;
344 usage
() if $opt_help;
345 usage
("Need one and only one podpage argument") unless @ARGV == 1;
347 $section = $opt_section || ($ARGV[0] =~ /\.pm$/
348 ?
$DEF_PM_SECTION : $DEF_SECTION);
349 $RP = $opt_release || $DEF_RELEASE;
350 $center = $opt_center || ($opt_official ?
$STD_CENTER : $DEF_CENTER);
351 $lax = $opt_lax || $DEF_LAX;
353 $CFont = $opt_fixed || $DEF_FIXED;
355 if (length($CFont) == 2) {
356 $CFont_embed = "\\f($CFont";
358 elsif (length($CFont) == 1) {
359 $CFont_embed = "\\f$CFont";
362 die "roff font should be 1 or 2 chars, not `$CFont_embed'";
365 $date = $opt_date || $DEF_DATE;
367 for (qw{NAME DESCRIPTION
}) {
368 # for (qw{NAME DESCRIPTION AUTHOR}) {
371 $wanna_see{SYNOPSIS
}++ if $section =~ /^3/;
374 $name = @ARGV ?
$ARGV[0] : "<STDIN>";
376 if ($section =~ /^1/) {
377 require File
::Basename
;
378 $name = uc File
::Basename
::basename
($name);
380 $name =~ s/\.(pod|p[lm])$//i;
382 # Lose everything up to the first of
383 # */lib/*perl* standard or site_perl module
384 # */*perl*/lib from -D prefix=/opt/perl
385 # */*perl*/ random module hierarchy
388 if ($name =~ s
-^.*?
/lib/[^/]*perl[^/]*/--i
389 or $name =~ s
-^.*?
/[^/]*perl
[^/]*/lib
/--i
390 or $name =~ s
-^.*?
/[^/]*perl
[^/]*/--i
) {
391 # Lose ^site(_perl)?/.
392 $name =~ s
-^site
(_perl
)?
/--;
393 # Lose ^arch/. (XXX should we use Config? Just for archname?)
394 $name =~ s
~^(.*-$^O
|$^O
-.*)/~~o
;
396 $name =~ s
-^\d
+\
.\d
+/--;
399 # Translate Getopt/Long to Getopt::Long, etc.
402 if ($name ne 'something') {
404 open(F
, "< $ARGV[0]") || die "can't open $ARGV[0]: $!";
407 if (/^=head1\s+NAME\s*$/) { # an /m would forgive mistakes
409 unless (/\s*-+\s+/) {
411 warn "$0: Improper man page - no dash in NAME header in paragraph $. of $ARGV[0]\n"
413 my @n = split /\s+-+\s+/;
416 warn "$0: Improper man page - malformed NAME header in paragraph $. of $ARGV[0]\n"
426 next if /^=cut\b/; # DB_File and Net::Ping have =cut before NAME
427 next if /^=pod\b/; # It is OK to have =pod before NAME
428 next if /^=(for|begin|end)\s+comment\b/; # It is OK to have =for =begin or =end comment before NAME
429 die "$0: Invalid man page - 1st pod line is not NAME in $ARGV[0]\n" unless $lax;
431 die "$0: Invalid man page - no documentation in $ARGV[0]\n" unless $lax;
438 ''' \RCSfile\$\$Revision\\Date\
456 .ie \\\\n(.\$>=3 .ne \\\\\$3
458 .IP "\\\\\$1" \\\\\$2
472 ''' Set up \\*(-- to give an unbreakable dash;
473 ''' string Tr holds user defined translation string.
474 ''' Bell System Logo is used as a dummy character.
476 .tr \\(*W-|\\(bv\\*(Tr
480 .if (\\n(.H=4u)&(1m=24u) .ds -- \\(*W\\h'-12u'\\(*W\\h'-12u'-\\" diablo 10 pitch
481 .if (\\n(.H=4u)&(1m=20u) .ds -- \\(*W\\h'-12u'\\(*W\\h'-8u'-\\" diablo 12 pitch
484 ''' \\*(M", \\*(S", \\*(N" and \\*(T" are the equivalent of
485 ''' \\*(L" and \\*(R", except that they are used on ".xx" lines,
486 ''' such as .IP and .SH, which do another additional levels of
487 ''' double-quote interpretation
519 .\" If the F register is turned on, we'll generate
520 .\" index entries out stderr for the following things:
525 .\" X<> Xref (embedded
526 .\" Of course, you have to process the output yourself
527 .\" in some meaninful fashion.
530 .tm Index:\\$1\t\\n%\t"\\$2"
538 .TH $name $section "$RP" "$date" "$center"
542 push(@Indices, qq{.IX Title
"$name $section"});
544 while (($name, $desc) = each %namedesc) {
545 for ($name, $desc) { s/^\s+//; s/\s+$//; }
546 push(@Indices, qq(.IX Name
"$name - $desc"\n));
552 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
553 .de CQ \" put $1 in typewriter font
555 print ".ft $CFont\n";
561 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
564 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
565 . \" AM - accent mark definitions
567 . \" fudge factors for nroff and troff
576 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
582 . \" simple accents for nroff and troff
595 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
596 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
597 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
598 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
599 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
600 . ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
601 . ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
602 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
603 . ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
605 . \" troff and (daisy-wheel) nroff accents
606 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
607 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
608 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
609 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
610 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
611 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
612 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
613 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
614 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
615 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
616 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
617 .ds ae a\h'-(\w'a'u*4/10)'e
618 .ds Ae A\h'-(\w'A'u*4/10)'E
619 .ds oe o\h'-(\w'o'u*4/10)'e
620 .ds Oe O\h'-(\w'O'u*4/10)'E
621 . \" corrections for vroff
622 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
623 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
624 . \" for low resolution devices (crt and lpr)
625 .if \n(.H>23 .if \n(.V>19 \
629 . ds v \h'-1'\o'\(aa\(ga'
650 # Unrolling [^A-Z>]|[A-Z](?!<) gives: // MRE pp 165.
651 my $nonest = '(?:[^A-Z>]*(?:[A-Z](?!<)[^A-Z>]*)*)';
659 if (/^=end\s+$begun/) {
662 elsif ($begun =~ /^(roff|man)$/) {
669 # Translate verbatim paragraph
672 @lines = split(/\n/);
675 {^( [^\t]* ) \t ( \t* ) }
676 { $1 . ' ' x
(8 - (length($1)%8) + 8 * (length($2))) }ex
;
681 makespace
() unless $verbatim++;
682 print ".Vb $lines\n";
683 print join("\n", @lines), "\n";
691 if (/^=for\s+(\S+)\s*/s) {
692 if ($1 eq "man" or $1 eq "roff") {
693 print STDOUT
$',"\n\n";
699 elsif (/^=begin\s+(\S+)\s*/s) {
701 if ($1 eq "man" or $1 eq "roff") {
702 print STDOUT $'."\n\n";
707 # check for things that'll hosed our noremap scheme; affects $_
712 # trofficate backslashes; must do it before what happens below
713 s/\\/noremap('\\e')/ge;
715 # protect leading periods and quotes against *roff
716 # mistaking them for directives
717 s/^(?:[A-Z]<)?[.']/\\&$&/gm;
719 # first hide the escapes in case we need to
720 # intuit something and get it wrong due to fmting
722 1 while s/([A-Z]<$nonest>)/noremap($1)/ge;
724 # func() is a reference to a perl function
732 # func(n) is a reference to a perl function or a man page
740 # convert simple variable references
741 s/(\s+)([\$\@%][\w:]+)(?!\()/${1}C<$2>/g;
751 }x
&& $` !~ /([LCI]<[^<>]*|-)$/ && !/^=\w/)
753 warn "$0: bad option in paragraph $. of $ARGV: ``$1'' should be [LCI]<$1>\n";
757 while (/(-[a-zA-Z])\b/g && $` !~ /[\w\-]$/) {
758 warn "$0: bad option in paragraph $. of $ARGV: ``$1'' should be [CB]<$1>\n";
762 # put it back so we get the <> processed again;
763 clear_noremap
(0); # 0 means leave the E's
766 # trofficate backslashes
767 s/\\/noremap('\\e')/ge;
771 # need to hide E<> first; they're processed in clear_noremap
772 s/(E<[^<>]+>)/noremap($1)/ge;
776 while ($maxnest-- && /[A-Z]</) {
778 # can't do C font here
779 s/([BI])<($nonest)>/font($1) . $2 . font('R')/eg;
781 # files and filelike refs in italics
782 s/F<($nonest)>/I<$1>/g;
784 # no break -- usually we want C<> for this
785 s/S<($nonest)>/nobreak($1)/eg;
787 # LREF: a la HREF L<show this text|man/section>
788 s
:L
<([^|>]+)\
|[^>]+>:$1:g
;
790 # LREF: a manpage(3f)
791 s
:L
<([a
-zA
-Z
][^\s\
/]+)(\
([^\
)]+\
))?
>:the I
<$1>$2 manpage
:g
;
793 # LREF: an =item on another manpage
803 } {the C
<$2> entry
in the I
<$1> manpage
}gx
;
805 # LREF: an =item on this manpage
817 } { internal_lrefs
($1) }gex
;
819 # LREF: a =head2 (head1?), maybe on a manpage, maybe right here
820 # the "func" can disambiguate
830 $1 # if no $1, assume it means on this page.
831 ?
"the section on I<$2> in the I<$1> manpage"
832 : "the section on I<$2>"
834 }gesx
; # s in case it goes over multiple lines, so . matches \n
838 # comes last because not subject to reprocessing
839 s/C<($nonest)>/noremap("${CFont_embed}${1}\\fR")/eg;
843 $needspace = 0; # Assume this.
847 ($Cmd, $_) = split(' ', $_, 2);
850 if ($Cmd eq 'head1') {
853 elsif ($Cmd eq 'head2') {
856 elsif ($Cmd eq 'item') {
870 elsif ($Cmd eq 'head1') {
872 delete $wanna_see{$_} if exists $wanna_see{$_};
873 print qq{.SH
"$_"\n};
874 push(@Indices, qq{.IX Header
"$_"\n});
876 elsif ($Cmd eq 'head2') {
877 print qq{.Sh
"$_"\n};
878 push(@Indices, qq{.IX Subsection
"$_"\n});
880 elsif ($Cmd eq 'over') {
881 push(@indent,$indent);
882 $indent += ($_ + 0) || 5;
884 elsif ($Cmd eq 'back') {
885 $indent = pop(@indent);
886 warn "$0: Unmatched =back in paragraph $. of $ARGV\n" unless defined $indent;
889 elsif ($Cmd eq 'item') {
890 s/^\*( |$)/\\(bu$1/g;
891 # if you know how to get ":s please do
892 s/\\\*\(L"([^"]+?)\\\*\(R"/'$1'/g;
893 s/\\\*\(L"([^"]+?)""/'$1'/g;
894 s/[^"]""([^"]+?)""[^"]/'$1'/g;
895 # here do something about the $" in perlvar?
896 print STDOUT
qq{.Ip
"$_" $indent\n};
897 push(@Indices, qq{.IX Item
"$_"\n});
899 elsif ($Cmd eq 'pod') {
900 # this is just a comment
903 warn "$0: Unrecognized pod directive in paragraph $. of $ARGV: $Cmd\n";
922 if (%wanna_see && !$lax) {
923 @missing = keys %wanna_see;
924 warn "$0: $Filename is missing required section"
925 . (@missing > 1 && "s")
930 foreach (@Indices) { print "$_\n"; }
935 #########################################################################
939 $string =~ s/ /\\ /g;
946 s/X<(.*?)>/mkindex($1)/ge;
948 # translate the minus in foo-bar into foo\-bar for roff
949 s/([^0-9a-z-])-([^-])/$1\\-$2/g;
951 # make -- into the string version \*(-- (defined above)
953 s/"--([^"])/"\\*(--$1/g; # should be a better way
954 s/([^"])--"/$1\\*(--"/g;
956 # fix up quotes; this is somewhat tricky
963 elsif ( $indot >= 2 ) {
968 s/(^|\s)(['"])/noremap("$1\\*($dotmacroL$2")/ge;
969 s/(['"])($|[\-\s,;\\!?.])/noremap("\\*($dotmacroR$1$2")/ge;
972 #s/(?!")(?:.)--(?!")(?:.)/\\*(--/g;
973 #s/(?:(?!")(?:.)--(?:"))|(?:(?:")--(?!")(?:.))/\\*(--/g;
976 # make sure that func() keeps a bit a space tween the parens
977 ### s/\b\(\)/\\|()/g;
978 ### s/\b\(\)/(\\|)/g;
980 # make C++ into \*C+, which is a squinched version (defined above)
983 # make double underbars have a little tiny space between them
986 # PI goes to \*(PI (defined above)
987 s/\bPI\b/noremap('\\*(PI')/ge;
989 # make all caps a teeny bit smaller, but don't muck with embedded code literals
990 my $hidCFont = font
('C');
991 if ($Cmd !~ /^head1/) { # SH already makes smaller
992 # /g isn't enough; 1 while or we'll be off
995 # (?!$hidCFont)(..|^.|^)
998 # [A-Z][\/A-Z+:\-\d_$.]+
1002 # } {$1\\s-1$2\\s0}gmox;
1005 (?
!$hidCFont)(..|^.|^)
1007 \b[A
-Z
]{2,}[\
/A
-Z
+:\
-\d_\
$]*\b
1010 $1 . noremap
( '\\s-1' . $2 . '\\s0' )
1016 # make troff just be normal, but make small nroff get quoted
1017 # decided to just put the quotes in the text; sigh;
1019 local($_,$prev) = @_;
1020 noremap
(qq{.CQ
"$_" \n\\&});
1034 my @entries = split m
:\s
*/\s
*:, $entry;
1035 push @Indices, ".IX Xref " . join ' ', map {qq("$_")} @entries;
1040 local($font) = shift;
1041 return '\\f' . noremap
($font);
1045 local($thing_to_hide) = shift;
1046 $thing_to_hide =~ tr/\000-\177/\200-\377/;
1047 return $thing_to_hide;
1051 # escape high bit characters in input stream
1052 s/([\200-\377])/"E<".ord($1).">"/ge;
1056 my $ready_to_print = $_[0];
1058 tr/\200-\377/\000-\177/;
1060 # trofficate backslashes
1061 # s/(?!\\e)(?:..|^.|^)\\/\\e/g;
1063 # now for the E<>s, which have been hidden until now
1064 # otherwise the interative \w<> processing would have
1065 # been hosed by the E<gt>
1078 exists $HTML_Escapes{$3}
1079 ?
do { $HTML_Escapes{$3} }
1081 warn "$0: Unknown escape in paragraph $. of $ARGV: ``$&''\n";
1085 }egx
if $ready_to_print;
1088 sub internal_lrefs
{
1090 local $trailing_and = s/and\s+$// ?
"and " : "";
1092 s{L</([^>]+)>}{$1}g;
1093 my(@items) = split( /(?:,?\s+(?:and\s+)?)/ );
1094 my $retstr = "the ";
1096 for ($i = 0; $i <= $#items; $i++) {
1097 $retstr .= "C<$items[$i]>";
1098 $retstr .= ", " if @items > 2 && $i != $#items;
1099 $retstr .= " and " if $i+2 == @items;
1102 $retstr .= " entr" . ( @items > 1 ?
"ies" : "y" )
1103 . " elsewhere in this document";
1104 # terminal space to avoid words running together (pattern used
1105 # strips terminal spaces)
1106 $retstr .= " " if length $trailing_and;
1107 $retstr .= $trailing_and;
1115 'amp' => '&', # ampersand
1116 'lt' => '<', # left chevron, less-than
1117 'gt' => '>', # right chevron, greater-than
1118 'quot' => '"', # double quote
1120 "Aacute" => "A\\*'", # capital A, acute accent
1121 "aacute" => "a\\*'", # small a, acute accent
1122 "Acirc" => "A\\*^", # capital A, circumflex accent
1123 "acirc" => "a\\*^", # small a, circumflex accent
1124 "AElig" => '\*(AE', # capital AE diphthong (ligature)
1125 "aelig" => '\*(ae', # small ae diphthong (ligature)
1126 "Agrave" => "A\\*`", # capital A, grave accent
1127 "agrave" => "A\\*`", # small a, grave accent
1128 "Aring" => 'A\\*o', # capital A, ring
1129 "aring" => 'a\\*o', # small a, ring
1130 "Atilde" => 'A\\*~', # capital A, tilde
1131 "atilde" => 'a\\*~', # small a, tilde
1132 "Auml" => 'A\\*:', # capital A, dieresis or umlaut mark
1133 "auml" => 'a\\*:', # small a, dieresis or umlaut mark
1134 "Ccedil" => 'C\\*,', # capital C, cedilla
1135 "ccedil" => 'c\\*,', # small c, cedilla
1136 "Eacute" => "E\\*'", # capital E, acute accent
1137 "eacute" => "e\\*'", # small e, acute accent
1138 "Ecirc" => "E\\*^", # capital E, circumflex accent
1139 "ecirc" => "e\\*^", # small e, circumflex accent
1140 "Egrave" => "E\\*`", # capital E, grave accent
1141 "egrave" => "e\\*`", # small e, grave accent
1142 "ETH" => '\\*(D-', # capital Eth, Icelandic
1143 "eth" => '\\*(d-', # small eth, Icelandic
1144 "Euml" => "E\\*:", # capital E, dieresis or umlaut mark
1145 "euml" => "e\\*:", # small e, dieresis or umlaut mark
1146 "Iacute" => "I\\*'", # capital I, acute accent
1147 "iacute" => "i\\*'", # small i, acute accent
1148 "Icirc" => "I\\*^", # capital I, circumflex accent
1149 "icirc" => "i\\*^", # small i, circumflex accent
1150 "Igrave" => "I\\*`", # capital I, grave accent
1151 "igrave" => "i\\*`", # small i, grave accent
1152 "Iuml" => "I\\*:", # capital I, dieresis or umlaut mark
1153 "iuml" => "i\\*:", # small i, dieresis or umlaut mark
1154 "Ntilde" => 'N\*~', # capital N, tilde
1155 "ntilde" => 'n\*~', # small n, tilde
1156 "Oacute" => "O\\*'", # capital O, acute accent
1157 "oacute" => "o\\*'", # small o, acute accent
1158 "Ocirc" => "O\\*^", # capital O, circumflex accent
1159 "ocirc" => "o\\*^", # small o, circumflex accent
1160 "Ograve" => "O\\*`", # capital O, grave accent
1161 "ograve" => "o\\*`", # small o, grave accent
1162 "Oslash" => "O\\*/", # capital O, slash
1163 "oslash" => "o\\*/", # small o, slash
1164 "Otilde" => "O\\*~", # capital O, tilde
1165 "otilde" => "o\\*~", # small o, tilde
1166 "Ouml" => "O\\*:", # capital O, dieresis or umlaut mark
1167 "ouml" => "o\\*:", # small o, dieresis or umlaut mark
1168 "szlig" => '\*8', # small sharp s, German (sz ligature)
1169 "THORN" => '\\*(Th', # capital THORN, Icelandic
1170 "thorn" => '\\*(th',, # small thorn, Icelandic
1171 "Uacute" => "U\\*'", # capital U, acute accent
1172 "uacute" => "u\\*'", # small u, acute accent
1173 "Ucirc" => "U\\*^", # capital U, circumflex accent
1174 "ucirc" => "u\\*^", # small u, circumflex accent
1175 "Ugrave" => "U\\*`", # capital U, grave accent
1176 "ugrave" => "u\\*`", # small u, grave accent
1177 "Uuml" => "U\\*:", # capital U, dieresis or umlaut mark
1178 "uuml" => "u\\*:", # small u, dieresis or umlaut mark
1179 "Yacute" => "Y\\*'", # capital Y, acute accent
1180 "yacute" => "y\\*'", # small y, acute accent
1181 "yuml" => "y\\*:", # small y, dieresis or umlaut mark