~vcs-imports/gawk/master

« back to all changes in this revision

Viewing changes to doc/texinfo.tex

  • Committer: Arnold D. Robbins
  • Date: 2012-11-25 19:54:48 UTC
  • mfrom: (319.1.122)
  • Revision ID: git-v1:9a9ff61bbd952c1263b55f82a269da5b09289a6b
Merge branch 'master' into array-iface

Show diffs side-by-side

added added

removed removed

Lines of Context:
3
3
% Load plain if necessary, i.e., if running under initex.
4
4
\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
5
5
%
6
 
\def\texinfoversion{2012-01-19.16}
 
6
\def\texinfoversion{2012-09-05.06}
7
7
%
8
8
% Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
9
9
% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
10
 
% 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
 
10
% 2007, 2008, 2009, 2010, 2011, 2012 Free Software Foundation, Inc.
11
11
%
12
12
% This texinfo.tex file is free software: you can redistribute it and/or
13
13
% modify it under the terms of the GNU General Public License as
28
28
%
29
29
% Please try the latest version of texinfo.tex before submitting bug
30
30
% reports; you can get the latest version from:
31
 
%   http://www.gnu.org/software/texinfo/ (the Texinfo home page), or
32
 
%   ftp://tug.org/tex/texinfo.tex
33
 
%     (and all CTAN mirrors, see http://www.ctan.org).
 
31
%   http://ftp.gnu.org/gnu/texinfo/ (the Texinfo release area), or
 
32
%   http://ftpmirror.gnu.org/texinfo/ (same, via a mirror), or
 
33
%   http://www.gnu.org/software/texinfo/ (the Texinfo home page)
34
34
% The texinfo.tex in any given distribution could well be out
35
35
% of date, so if that's what you're using, please check.
36
36
%
594
594
\def\:{\spacefactor=1000 }
595
595
 
596
596
% @* forces a line break.
597
 
\def\*{\hfil\break\hbox{}\ignorespaces}
 
597
\def\*{\unskip\hfil\break\hbox{}\ignorespaces}
598
598
 
599
599
% @/ allows a line break.
600
600
\let\/=\allowbreak
887
887
\def\popthisfilestack{\errthisfilestackempty}
888
888
\def\errthisfilestackempty{\errmessage{Internal error:
889
889
  the stack of filenames is empty.}}
890
 
 
 
890
%
891
891
\def\thisfile{}
892
892
 
893
893
% @center line
895
895
%
896
896
\parseargdef\center{%
897
897
  \ifhmode
898
 
    \let\next\centerH
 
898
    \let\centersub\centerH
899
899
  \else
900
 
    \let\next\centerV
 
900
    \let\centersub\centerV
901
901
  \fi
902
 
  \next{\hfil \ignorespaces#1\unskip \hfil}%
903
 
}
904
 
\def\centerH#1{%
905
 
  {%
906
 
    \hfil\break
907
 
    \advance\hsize by -\leftskip
908
 
    \advance\hsize by -\rightskip
909
 
    \line{#1}%
910
 
    \break
911
 
  }%
912
 
}
913
 
\def\centerV#1{\line{\kern\leftskip #1\kern\rightskip}}
 
902
  \centersub{\hfil \ignorespaces#1\unskip \hfil}%
 
903
  \let\centersub\relax % don't let the definition persist, just in case
 
904
}
 
905
\def\centerH#1{{%
 
906
  \hfil\break
 
907
  \advance\hsize by -\leftskip
 
908
  \advance\hsize by -\rightskip
 
909
  \line{#1}%
 
910
  \break
 
911
}}
 
912
%
 
913
\newcount\centerpenalty
 
914
\def\centerV#1{%
 
915
  % The idea here is the same as in \startdefun, \cartouche, etc.: if
 
916
  % @center is the first thing after a section heading, we need to wipe
 
917
  % out the negative parskip inserted by \sectionheading, but still
 
918
  % prevent a page break here.
 
919
  \centerpenalty = \lastpenalty
 
920
  \ifnum\centerpenalty>10000 \vskip\parskip \fi
 
921
  \ifnum\centerpenalty>9999 \penalty\centerpenalty \fi
 
922
  \line{\kern\leftskip #1\kern\rightskip}%
 
923
}
914
924
 
915
925
% @sp n   outputs n lines of vertical space
916
 
 
 
926
%
917
927
\parseargdef\sp{\vskip #1\baselineskip}
918
928
 
919
929
% @comment ...line which is ignored...
920
930
% @c is the same as @comment
921
931
% @ignore ... @end ignore  is another way to write a comment
922
 
 
 
932
%
923
933
\def\comment{\begingroup \catcode`\^^M=\other%
924
934
\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other%
925
935
\commentxxx}
926
936
{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}}
927
 
 
 
937
%
928
938
\let\c=\comment
929
939
 
930
940
% @paragraphindent NCHARS
1107
1117
% #1 is a control sequence in which to do the replacements,
1108
1118
% which we \xdef.
1109
1119
\def\txiescapepdf#1{%
1110
 
  \ifx\pdfescapestring\relax
 
1120
  \ifx\pdfescapestring\thisisundefined
1111
1121
    % No primitive available; should we give a warning or log?
1112
1122
    % Many times it won't matter.
1113
1123
  \else
1173
1183
  %
1174
1184
  % #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto).
1175
1185
  \def\dopdfimage#1#2#3{%
1176
 
    \def\imagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}%
1177
 
    \def\imageheight{#3}\setbox2 = \hbox{\ignorespaces #3}%
 
1186
    \def\pdfimagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}%
 
1187
    \def\pdfimageheight{#3}\setbox2 = \hbox{\ignorespaces #3}%
1178
1188
    %
1179
1189
    % pdftex (and the PDF format) support .pdf, .png, .jpg (among
1180
1190
    % others).  Let's try in that order, PDF first since if
1212
1222
    \else
1213
1223
      \immediate\pdfximage
1214
1224
    \fi
1215
 
      \ifdim \wd0 >0pt width \imagewidth \fi
1216
 
      \ifdim \wd2 >0pt height \imageheight \fi
 
1225
      \ifdim \wd0 >0pt width \pdfimagewidth \fi
 
1226
      \ifdim \wd2 >0pt height \pdfimageheight \fi
1217
1227
      \ifnum\pdftexversion<13
1218
1228
         #1.\pdfimgext
1219
1229
       \else
1357
1367
  \def\skipspaces#1{\def\PP{#1}\def\D{|}%
1358
1368
    \ifx\PP\D\let\nextsp\relax
1359
1369
    \else\let\nextsp\skipspaces
1360
 
      \ifx\p\space\else\addtokens{\filename}{\PP}%
1361
 
        \advance\filenamelength by 1
1362
 
      \fi
 
1370
      \addtokens{\filename}{\PP}%
 
1371
      \advance\filenamelength by 1
1363
1372
    \fi
1364
1373
    \nextsp}
1365
 
  \def\getfilename#1{\filenamelength=0\expandafter\skipspaces#1|\relax}
 
1374
  \def\getfilename#1{%
 
1375
    \filenamelength=0
 
1376
    % If we don't expand the argument now, \skipspaces will get
 
1377
    % snagged on things like "@value{foo}".
 
1378
    \edef\temp{#1}%
 
1379
    \expandafter\skipspaces\temp|\relax
 
1380
  }
1366
1381
  \ifnum\pdftexversion < 14
1367
1382
    \let \startlink \pdfannotlink
1368
1383
  \else
1459
1474
\def\ttsl{\setfontstyle{ttsl}}
1460
1475
 
1461
1476
 
1462
 
% Default leading.
1463
 
\newdimen\textleading  \textleading = 13.2pt
1464
 
 
1465
1477
% Set the baselineskip to #1, and the lineskip and strut size
1466
1478
% correspondingly.  There is no deep meaning behind these magic numbers
1467
1479
% used as factors; they just match (closely enough) what Knuth defined.
1473
1485
% can get a sort of poor man's double spacing by redefining this.
1474
1486
\def\baselinefactor{1}
1475
1487
%
 
1488
\newdimen\textleading
1476
1489
\def\setleading#1{%
1477
1490
  \dimen0 = #1\relax
1478
1491
  \normalbaselineskip = \baselinefactor\dimen0
1745
1758
\fi\fi
1746
1759
 
1747
1760
 
1748
 
% Set the font macro #1 to the font named #2, adding on the
1749
 
% specified font prefix (normally `cm').
 
1761
% Set the font macro #1 to the font named \fontprefix#2.
1750
1762
% #3 is the font's design size, #4 is a scale factor, #5 is the CMap
1751
 
% encoding (currently only OT1, OT1IT and OT1TT are allowed, pass
1752
 
% empty to omit).
 
1763
% encoding (only OT1, OT1IT and OT1TT are allowed, or empty to omit).
 
1764
% Example:
 
1765
% #1 = \textrm
 
1766
% #2 = \rmshape
 
1767
% #3 = 10
 
1768
% #4 = \mainmagstep
 
1769
% #5 = OT1
 
1770
%
1753
1771
\def\setfont#1#2#3#4#5{%
1754
1772
  \font#1=\fontprefix#2#3 scaled #4
1755
1773
  \csname cmap#5\endcsname#1%
1756
1774
}
1757
1775
% This is what gets called when #5 of \setfont is empty.
1758
1776
\let\cmap\gobble
1759
 
% emacs-page end of cmaps
 
1777
%
 
1778
% (end of cmaps)
1760
1779
 
1761
1780
% Use cm as the default font prefix.
1762
1781
% To specify the font prefix, you must define \fontprefix
1766
1785
\fi
1767
1786
% Support font families that don't use the same naming scheme as CM.
1768
1787
\def\rmshape{r}
1769
 
\def\rmbshape{bx}               %where the normal face is bold
 
1788
\def\rmbshape{bx}               % where the normal face is bold
1770
1789
\def\bfshape{b}
1771
1790
\def\bxshape{bx}
1772
1791
\def\ttshape{tt}
1781
1800
\def\scshape{csc}
1782
1801
\def\scbshape{csc}
1783
1802
 
1784
 
% Definitions for a main text size of 11pt.  This is the default in
1785
 
% Texinfo.
 
1803
% Definitions for a main text size of 11pt.  (The default in Texinfo.)
1786
1804
%
1787
1805
\def\definetextfontsizexi{%
1788
1806
% Text fonts (11.2pt, magstep1).
1907
1925
\textleading = 13.2pt % line spacing for 11pt CM
1908
1926
\textfonts            % reset the current fonts
1909
1927
\rm
1910
 
} % end of 11pt text font size definitions
 
1928
} % end of 11pt text font size definitions, \definetextfontsizexi
1911
1929
 
1912
1930
 
1913
1931
% Definitions to make the main text be 10pt Computer Modern, with
2039
2057
\textleading = 12pt   % line spacing for 10pt CM
2040
2058
\textfonts            % reset the current fonts
2041
2059
\rm
2042
 
} % end of 10pt text font size definitions
 
2060
} % end of 10pt text font size definitions, \definetextfontsizex
2043
2061
 
2044
2062
 
2045
2063
% We provide the user-level command
2430
2448
% @samp.
2431
2449
\def\samp#1{{\setupmarkupstyle{samp}\lq\tclose{#1}\rq\null}}
2432
2450
 
2433
 
% definition of @key that produces a lozenge.  Doesn't adjust to text size.
2434
 
%\setfont\keyrm\rmshape{8}{1000}{OT1}
2435
 
%\font\keysy=cmsy9
2436
 
%\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{%
2437
 
%  \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{%
2438
 
%    \vbox{\hrule\kern-0.4pt
2439
 
%     \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}%
2440
 
%    \kern-0.4pt\hrule}%
2441
 
%  \kern-.06em\raise0.4pt\hbox{\angleright}}}}
2442
 
 
2443
 
% definition of @key with no lozenge.  If the current font is already
2444
 
% monospace, don't change it; that way, we respect @kbdinputstyle.  But
2445
 
% if it isn't monospace, then use \tt.
2446
 
%
2447
 
\def\key#1{{\setupmarkupstyle{key}%
2448
 
  \nohyphenation
2449
 
  \ifmonospace\else\tt\fi
2450
 
  #1}\null}
2451
 
 
2452
 
% ctrl is no longer a Texinfo command.
2453
 
\def\ctrl #1{{\tt \rawbackslash \hat}#1}
2454
 
 
2455
 
% @file, @option are the same as @samp.
2456
 
\let\file=\samp
2457
 
\let\option=\samp
2458
 
 
2459
 
% @code is a modification of @t,
2460
 
% which makes spaces the same size as normal in the surrounding text.
 
2451
% @indicateurl is \samp, that is, with quotes.
 
2452
\let\indicateurl=\samp
 
2453
 
 
2454
% @code (and similar) prints in typewriter, but with spaces the same
 
2455
% size as normal in the surrounding text, without hyphenation, etc.
 
2456
% This is a subroutine for that.
2461
2457
\def\tclose#1{%
2462
2458
  {%
2463
2459
    % Change normal interword space to be same as for the current font.
2482
2478
% We *must* turn on hyphenation at `-' and `_' in @code.
2483
2479
% Otherwise, it is too hard to avoid overfull hboxes
2484
2480
% in the Emacs manual, the Library manual, etc.
2485
 
 
 
2481
%
2486
2482
% Unfortunately, TeX uses one parameter (\hyphenchar) to control
2487
2483
% both hyphenation at - and hyphenation within words.
2488
2484
% We must therefore turn them both off (\tclose does that)
2546
2542
  \fi\fi
2547
2543
}
2548
2544
 
 
2545
% For @command, @env, @file, @option quotes seem unnecessary,
 
2546
% so use \code rather than \samp.
 
2547
\let\command=\code
 
2548
\let\env=\code
 
2549
\let\file=\code
 
2550
\let\option=\code
 
2551
 
2549
2552
% @uref (abbreviation for `urlref') takes an optional (comma-separated)
2550
2553
% second argument specifying the text to display and an optional third
2551
2554
% arg as text to display instead of (rather than in addition to) the url
2725
2728
\else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi
2726
2729
\else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi}
2727
2730
 
2728
 
% For @indicateurl, @env, @command quotes seem unnecessary, so use \code.
2729
 
\let\indicateurl=\code
2730
 
\let\env=\code
2731
 
\let\command=\code
 
2731
% definition of @key that produces a lozenge.  Doesn't adjust to text size.
 
2732
%\setfont\keyrm\rmshape{8}{1000}{OT1}
 
2733
%\font\keysy=cmsy9
 
2734
%\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{%
 
2735
%  \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{%
 
2736
%    \vbox{\hrule\kern-0.4pt
 
2737
%     \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}%
 
2738
%    \kern-0.4pt\hrule}%
 
2739
%  \kern-.06em\raise0.4pt\hbox{\angleright}}}}
 
2740
 
 
2741
% definition of @key with no lozenge.  If the current font is already
 
2742
% monospace, don't change it; that way, we respect @kbdinputstyle.  But
 
2743
% if it isn't monospace, then use \tt.
 
2744
%
 
2745
\def\key#1{{\setupmarkupstyle{key}%
 
2746
  \nohyphenation
 
2747
  \ifmonospace\else\tt\fi
 
2748
  #1}\null}
2732
2749
 
2733
2750
% @clicksequence{File @click{} Open ...}
2734
2751
\def\clicksequence#1{\begingroup #1\endgroup}
2836
2853
  }
2837
2854
}
2838
2855
 
 
2856
% ctrl is no longer a Texinfo command, but leave this definition for fun.
 
2857
\def\ctrl #1{{\tt \rawbackslash \hat}#1}
 
2858
 
2839
2859
% @inlinefmt{FMTNAME,PROCESSED-TEXT} and @inlineraw{FMTNAME,RAW-TEXT}.
2840
2860
% Ignore unless FMTNAME == tex; then it is like @iftex and @tex,
2841
2861
% except specified as a normal braced arg, so no newlines to worry about.
3126
3146
  % hopefully nobody will notice/care.
3127
3147
  \edef\ecsize{\csname\curfontsize ecsize\endcsname}%
3128
3148
  \edef\nominalsize{\csname\curfontsize nominalsize\endcsname}%
3129
 
  \ifx\curfontstyle\bfstylename
3130
 
    % bold:
3131
 
    \font\thisecfont = ecb\ifusingit{i}{x}\ecsize \space at \nominalsize
 
3149
  \ifmonospace
 
3150
    % typewriter:
 
3151
    \font\thisecfont = ectt\ecsize \space at \nominalsize
3132
3152
  \else
3133
 
    % regular:
3134
 
    \font\thisecfont = ec\ifusingit{ti}{rm}\ecsize \space at \nominalsize
 
3153
    \ifx\curfontstyle\bfstylename
 
3154
      % bold:
 
3155
      \font\thisecfont = ecb\ifusingit{i}{x}\ecsize \space at \nominalsize
 
3156
    \else
 
3157
      % regular:
 
3158
      \font\thisecfont = ec\ifusingit{ti}{rm}\ecsize \space at \nominalsize
 
3159
    \fi
3135
3160
  \fi
3136
3161
  \thisecfont
3137
3162
}
3244
3269
  \finishedtitlepagetrue
3245
3270
}
3246
3271
 
 
3272
% Settings used for typesetting titles: no hyphenation, no indentation,
 
3273
% don't worry much about spacing, ragged right.  This should be used
 
3274
% inside a \vbox, and fonts need to be set appropriately first.  Because
 
3275
% it is always used for titles, nothing else, we call \rmisbold.  \par
 
3276
% should be specified before the end of the \vbox, since a vbox is a group.
 
3277
 
3278
\def\raggedtitlesettings{%
 
3279
  \rmisbold
 
3280
  \hyphenpenalty=10000
 
3281
  \parindent=0pt
 
3282
  \tolerance=5000
 
3283
  \ptexraggedright
 
3284
}
 
3285
 
3247
3286
% Macros to be used within @titlepage:
3248
3287
 
3249
3288
\let\subtitlerm=\tenrm
3251
3290
 
3252
3291
\parseargdef\title{%
3253
3292
  \checkenv\titlepage
3254
 
  \leftline{\titlefonts\rmisbold #1}
 
3293
  \vbox{\titlefonts \raggedtitlesettings #1\par}%
3255
3294
  % print a rule at the page bottom also.
3256
3295
  \finishedtitlepagefalse
3257
3296
  \vskip4pt \hrule height 4pt width \hsize \vskip4pt
4188
4227
}
4189
4228
\def\ifsetfail{\doignore{ifset}}
4190
4229
 
4191
 
% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been
 
4230
% @ifclear VAR ... @end executes the `...' iff VAR has never been
4192
4231
% defined with @set, or has been undefined with @clear.
4193
4232
%
4194
4233
% The `\else' inside the `\doifset' parameter is a trick to reuse the
4199
4238
\def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}}
4200
4239
\def\ifclearfail{\doignore{ifclear}}
4201
4240
 
 
4241
% @ifcommandisdefined CMD ... @end executes the `...' if CMD (written
 
4242
% without the @) is in fact defined.  We can only feasibly check at the
 
4243
% TeX level, so something like `mathcode' is going to considered
 
4244
% defined even though it is not a Texinfo command.
 
4245
 
4246
\makecond{ifcommanddefined}
 
4247
\def\ifcommanddefined{\parsearg{\doifcmddefined{\let\next=\ifcmddefinedfail}}}
 
4248
%
 
4249
\def\doifcmddefined#1#2{{%
 
4250
    \makevalueexpandable
 
4251
    \let\next=\empty
 
4252
    \expandafter\ifx\csname #2\endcsname\relax
 
4253
      #1% If not defined, \let\next as above.
 
4254
    \fi
 
4255
    \expandafter
 
4256
  }\next
 
4257
}
 
4258
\def\ifcmddefinedfail{\doignore{ifcommanddefined}}
 
4259
 
 
4260
% @ifcommandnotdefined CMD ... handlded similar to @ifclear above.
 
4261
\makecond{ifcommandnotdefined}
 
4262
\def\ifcommandnotdefined{%
 
4263
  \parsearg{\doifcmddefined{\else \let\next=\ifcmdnotdefinedfail}}}
 
4264
\def\ifcmdnotdefinedfail{\doignore{ifcommandnotdefined}}
 
4265
 
 
4266
% Set the `txicommandconditionals' variable, so documents have a way to
 
4267
% test if the @ifcommand...defined conditionals are available.
 
4268
\set txicommandconditionals
 
4269
 
4202
4270
% @dircategory CATEGORY  -- specify a category of the dir file
4203
4271
% which this file should belong to.  Ignore this in TeX.
4204
4272
\let\dircategory=\comment
4435
4503
  \definedummyword\guillemetright
4436
4504
  \definedummyword\guilsinglleft
4437
4505
  \definedummyword\guilsinglright
 
4506
  \definedummyword\lbracechar
4438
4507
  \definedummyword\leq
4439
4508
  \definedummyword\minus
4440
4509
  \definedummyword\ogonek
4447
4516
  \definedummyword\quoteleft
4448
4517
  \definedummyword\quoteright
4449
4518
  \definedummyword\quotesinglbase
 
4519
  \definedummyword\rbracechar
4450
4520
  \definedummyword\result
4451
4521
  \definedummyword\textdegree
4452
4522
  %
4498
4568
  \definedummyword\t
4499
4569
  %
4500
4570
  % Commands that take arguments.
 
4571
  \definedummyword\abbr
4501
4572
  \definedummyword\acronym
4502
4573
  \definedummyword\anchor
4503
4574
  \definedummyword\cite
4509
4580
  \definedummyword\emph
4510
4581
  \definedummyword\env
4511
4582
  \definedummyword\file
 
4583
  \definedummyword\image
4512
4584
  \definedummyword\indicateurl
 
4585
  \definedummyword\inforef
4513
4586
  \definedummyword\kbd
4514
4587
  \definedummyword\key
4515
4588
  \definedummyword\math
4556
4629
  % content at all.  So for index sorting, we map @{ and @} to strings
4557
4630
  % starting with |, since that ASCII character is between ASCII { and }.
4558
4631
  \def\{{|a}%
 
4632
  \def\lbracechar{|a}%
 
4633
  %
4559
4634
  \def\}{|b}%
 
4635
  \def\rbracechar{|b}%
4560
4636
  %
4561
4637
  % Non-English letters.
4562
4638
  \def\AA{AA}%
4732
4808
%
4733
4809
% ..., ready, GO:
4734
4810
%
4735
 
\def\safewhatsit#1{%
4736
 
\ifhmode
 
4811
\def\safewhatsit#1{\ifhmode
4737
4812
  #1%
4738
 
\else
 
4813
 \else
4739
4814
  % \lastskip and \lastpenalty cannot both be nonzero simultaneously.
4740
4815
  \whatsitskip = \lastskip
4741
4816
  \edef\lastskipmacro{\the\lastskip}%
4759
4834
    % to re-insert the same penalty (values >10000 are used for various
4760
4835
    % signals); since we just inserted a non-discardable item, any
4761
4836
    % following glue (such as a \parskip) would be a breakpoint.  For example:
4762
 
    %
4763
4837
    %   @deffn deffn-whatever
4764
4838
    %   @vindex index-whatever
4765
4839
    %   Description.
4772
4846
    % (the whatsit from the \write), so we must insert a \nobreak.
4773
4847
    \nobreak\vskip\whatsitskip
4774
4848
  \fi
4775
 
\fi
4776
 
}
 
4849
\fi}
4777
4850
 
4778
4851
% The index entry written in the file actually looks like
4779
4852
%  \entry {sortstring}{page}{topic}
5520
5593
 
5521
5594
% Define @majorheading, @heading and @subheading
5522
5595
 
5523
 
% NOTE on use of \vbox for chapter headings, section headings, and such:
5524
 
%       1) We use \vbox rather than the earlier \line to permit
5525
 
%          overlong headings to fold.
5526
 
%       2) \hyphenpenalty is set to 10000 because hyphenation in a
5527
 
%          heading is obnoxious; this forbids it.
5528
 
%       3) Likewise, headings look best if no \parindent is used, and
5529
 
%          if justification is not attempted.  Hence \raggedright.
5530
 
 
5531
5596
\def\majorheading{%
5532
5597
  {\advance\chapheadingskip by 10pt \chapbreak }%
5533
5598
  \parsearg\chapheadingzzz
5535
5600
 
5536
5601
\def\chapheading{\chapbreak \parsearg\chapheadingzzz}
5537
5602
\def\chapheadingzzz#1{%
5538
 
  {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
5539
 
                    \parindent=0pt\ptexraggedright
5540
 
                    \rmisbold #1\hfill}}%
5541
 
  \bigskip \par\penalty 200\relax
 
5603
  \vbox{\chapfonts \raggedtitlesettings #1\par}%
 
5604
  \nobreak\bigskip \nobreak
5542
5605
  \suppressfirstparagraphindent
5543
5606
}
5544
5607
 
5697
5760
    %
5698
5761
    % Typeset the actual heading.
5699
5762
    \nobreak % Avoid page breaks at the interline glue.
5700
 
    \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \ptexraggedright
5701
 
          \hangindent=\wd0 \centerparametersmaybe
 
5763
    \vbox{\raggedtitlesettings \hangindent=\wd0 \centerparametersmaybe
5702
5764
          \unhbox0 #1\par}%
5703
5765
  }%
5704
5766
  \nobreak\bigskip % no page break after a chapter title
5720
5782
\def\setchapterstyle #1 {\csname CHAPF#1\endcsname}
5721
5783
%
5722
5784
\def\unnchfopen #1{%
5723
 
\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
5724
 
                       \parindent=0pt\ptexraggedright
5725
 
                       \rmisbold #1\hfill}}\bigskip \par\nobreak
 
5785
  \chapoddpage
 
5786
  \vbox{\chapfonts \raggedtitlesettings #1\par}%
 
5787
  \nobreak\bigskip\nobreak
5726
5788
}
5727
5789
\def\chfopen #1#2{\chapoddpage {\chapfonts
5728
5790
\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}%
5729
5791
\par\penalty 5000 %
5730
5792
}
5731
5793
\def\centerchfopen #1{%
5732
 
\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
5733
 
                       \parindent=0pt
5734
 
                       \hfill {\rmisbold #1}\hfill}}\bigskip \par\nobreak
 
5794
  \chapoddpage
 
5795
  \vbox{\chapfonts \raggedtitlesettings \hfill #1\hfill}%
 
5796
  \nobreak\bigskip \nobreak
5735
5797
}
5736
5798
\def\CHAPFopen{%
5737
5799
  \global\let\chapmacro=\chfopen
5876
5938
  %
5877
5939
  % We'll almost certainly start a paragraph next, so don't let that
5878
5940
  % glue accumulate.  (Not a breakpoint because it's preceded by a
5879
 
  % discardable item.)
 
5941
  % discardable item.)  However, when a paragraph is not started next
 
5942
  % (\startdefun, \cartouche, \center, etc.), this needs to be wiped out
 
5943
  % or the negative glue will cause weirdly wrong output, typically
 
5944
  % obscuring the section heading with something else.
5880
5945
  \vskip-\parskip
5881
5946
  %
5882
 
  % This is purely so the last item on the list is a known \penalty >
5883
 
  % 10000.  This is so \startdefun can avoid allowing breakpoints after
5884
 
  % section headings.  Otherwise, it would insert a valid breakpoint between:
5885
 
  %   @section sec-whatever
5886
 
  %   @deffn def-whatever
 
5947
  % This is so the last item on the main vertical list is a known
 
5948
  % \penalty > 10000, so \startdefun, etc., can recognize the situation
 
5949
  % and do the needful.
5887
5950
  \penalty 10001
5888
5951
}
5889
5952
 
6303
6366
  % If this cartouche directly follows a sectioning command, we need the
6304
6367
  % \parskip glue (backspaced over by default) or the cartouche can
6305
6368
  % collide with the section heading.
6306
 
  \ifnum\lastpenalty>10000 \vskip\parskip \fi
 
6369
  \ifnum\lastpenalty>10000 \vskip\parskip \penalty\lastpenalty \fi
6307
6370
  %
6308
6371
  \vbox\bgroup
6309
6372
      \baselineskip=0pt\parskip=0pt\lineskip=0pt
7793
7856
  \fi\fi
7794
7857
}
7795
7858
 
7796
 
 
 
7859
7797
7860
% @xref, @pxref, and @ref generate cross-references.  For \xrefX, #1 is
7798
7861
% the node name, #2 the name of the Info cross-reference, #3 the printed
7799
7862
% node name, #4 the name of the Info file, #5 the name of the printed
7803
7866
\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]}
7804
7867
\def\ref#1{\xrefX[#1,,,,,,,]}
7805
7868
%
7806
 
\newbox\topbox
 
7869
\newbox\toprefbox
7807
7870
\newbox\printedrefnamebox
 
7871
\newbox\infofilenamebox
7808
7872
\newbox\printedmanualbox
7809
7873
%
7810
7874
\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup
7811
7875
  \unsepspaces
7812
7876
  %
 
7877
  % Get args without leading/trailing spaces.
7813
7878
  \def\printedrefname{\ignorespaces #3}%
7814
7879
  \setbox\printedrefnamebox = \hbox{\printedrefname\unskip}%
7815
7880
  %
 
7881
  \def\infofilename{\ignorespaces #4}%
 
7882
  \setbox\infofilenamebox = \hbox{\infofilename\unskip}%
 
7883
  %
7816
7884
  \def\printedmanual{\ignorespaces #5}%
7817
7885
  \setbox\printedmanualbox  = \hbox{\printedmanual\unskip}%
7818
7886
  %
7845
7913
  \ifpdf
7846
7914
    {\indexnofonts
7847
7915
     \turnoffactive
 
7916
     \makevalueexpandable
7848
7917
     % This expands tokens, so do it after making catcode changes, so _
7849
 
     % etc. don't get their TeX definitions.
 
7918
     % etc. don't get their TeX definitions.  This ignores all spaces in
 
7919
     % #4, including (wrongly) those in the middle of the filename.
7850
7920
     \getfilename{#4}%
7851
7921
     %
 
7922
     % This (wrongly) does not take account of leading or trailing
 
7923
     % spaces in #1, which should be ignored.
7852
7924
     \edef\pdfxrefdest{#1}%
7853
 
     \txiescapepdf\pdfxrefdest
 
7925
     \ifx\pdfxrefdest\empty
 
7926
       \def\pdfxrefdest{Top}% no empty targets
 
7927
     \else
 
7928
       \txiescapepdf\pdfxrefdest  % escape PDF special chars
 
7929
     \fi
7854
7930
     %
7855
7931
     \leavevmode
7856
7932
     \startlink attr{/Border [0 0 0]}%
7883
7959
      \printedrefname
7884
7960
    \fi
7885
7961
    %
7886
 
    % if the user also gave the printed manual name (fifth arg), append
 
7962
    % If the user also gave the printed manual name (fifth arg), append
7887
7963
    % "in MANUALNAME".
7888
7964
    \ifdim \wd\printedmanualbox > 0pt
7889
7965
      \space \putwordin{} \cite{\printedmanual}%
7898
7974
    % this is a loss.  Therefore, we give the text of the node name
7899
7975
    % again, so it is as if TeX is seeing it for the first time.
7900
7976
    % 
7901
 
    % Cross-manual reference.  Only include the "Section ``foo'' in" if
7902
 
    % the foo is neither missing or Top.  Thus, @xref{,,,foo,The Foo Manual}
7903
 
    % outputs simply "see The Foo Manual".
7904
7977
    \ifdim \wd\printedmanualbox > 0pt
7905
 
      % What is the 7sp about?  The idea is that we also want to omit
7906
 
      % the Section part if we would be printing "Top", since they are
7907
 
      % clearly trying to refer to the whole manual.  But, this being
7908
 
      % TeX, we can't easily compare strings while ignoring the possible
7909
 
      % spaces before and after in the input.  By adding the arbitrary
7910
 
      % 7sp, we make it much less likely that a real node name would
7911
 
      % happen to have the same width as "Top" (e.g., in a monospaced font).
7912
 
      % I hope it will never happen in practice.
7913
 
      % 
7914
 
      % For the same basic reason, we retypeset the "Top" at every
7915
 
      % reference, since the current font is indeterminate.
7916
 
      % 
7917
 
      \setbox\topbox = \hbox{Top\kern7sp}%
7918
 
      \setbox2 = \hbox{\ignorespaces \printedrefname \unskip \kern7sp}%
7919
 
      \ifdim \wd2 > 7sp
7920
 
        \ifdim \wd2 = \wd\topbox \else
7921
 
          \putwordSection{} ``\printedrefname'' \putwordin{}\space
7922
 
        \fi
7923
 
      \fi
7924
 
      \cite{\printedmanual}%
 
7978
      % Cross-manual reference with a printed manual name.
 
7979
      % 
 
7980
      \crossmanualxref{\cite{\printedmanual\unskip}}%
 
7981
    %
 
7982
    \else\ifdim \wd\infofilenamebox > 0pt
 
7983
      % Cross-manual reference with only an info filename (arg 4), no
 
7984
      % printed manual name (arg 5).  This is essentially the same as
 
7985
      % the case above; we output the filename, since we have nothing else.
 
7986
      % 
 
7987
      \crossmanualxref{\code{\infofilename\unskip}}%
 
7988
    %
7925
7989
    \else
7926
 
      % Reference in this manual.
 
7990
      % Reference within this manual.
7927
7991
      %
7928
7992
      % _ (for example) has to be the character _ for the purposes of the
7929
7993
      % control sequence corresponding to the node, but it has to expand
7944
8008
      %
7945
8009
      % output the `page 3'.
7946
8010
      \turnoffactive \putwordpage\tie\refx{#1-pg}{}%
7947
 
    \fi
 
8011
    \fi\fi
7948
8012
  \fi
7949
8013
  \endlink
7950
8014
\endgroup}
7951
8015
 
 
8016
% Output a cross-manual xref to #1.  Used just above (twice).
 
8017
 
8018
% Only include the text "Section ``foo'' in" if the foo is neither
 
8019
% missing or Top.  Thus, @xref{,,,foo,The Foo Manual} outputs simply
 
8020
% "see The Foo Manual", the idea being to refer to the whole manual.
 
8021
 
8022
% But, this being TeX, we can't easily compare our node name against the
 
8023
% string "Top" while ignoring the possible spaces before and after in
 
8024
% the input.  By adding the arbitrary 7sp below, we make it much less
 
8025
% likely that a real node name would have the same width as "Top" (e.g.,
 
8026
% in a monospaced font).  Hopefully it will never happen in practice.
 
8027
 
8028
% For the same basic reason, we retypeset the "Top" at every
 
8029
% reference, since the current font is indeterminate.
 
8030
 
8031
\def\crossmanualxref#1{%
 
8032
  \setbox\toprefbox = \hbox{Top\kern7sp}%
 
8033
  \setbox2 = \hbox{\ignorespaces \printedrefname \unskip \kern7sp}%
 
8034
  \ifdim \wd2 > 7sp  % nonempty?
 
8035
    \ifdim \wd2 = \wd\toprefbox \else  % same as Top?
 
8036
      \putwordSection{} ``\printedrefname'' \putwordin{}\space
 
8037
    \fi
 
8038
  \fi
 
8039
  #1%
 
8040
}
 
8041
 
7952
8042
% This macro is called from \xrefX for the `[nodename]' part of xref
7953
8043
% output.  It's a separate macro only so it can be changed more easily,
7954
8044
% since square brackets don't work well in some documents.  Particularly
8316
8406
  it from ftp://tug.org/tex/epsf.tex.}
8317
8407
%
8318
8408
\def\image#1{%
8319
 
  \ifx\epsfbox\thisiundefined
 
8409
  \ifx\epsfbox\thisisundefined
8320
8410
    \ifwarnednoepsf \else
8321
8411
      \errhelp = \noepsfhelp
8322
8412
      \errmessage{epsf.tex not found, images will be ignored}%
8340
8430
  % If the image is by itself, center it.
8341
8431
  \ifvmode
8342
8432
    \imagevmodetrue
 
8433
  \else \ifx\centersub\centerV
 
8434
    % for @center @image, we need a vbox so we can have our vertical space
 
8435
    \imagevmodetrue
 
8436
    \vbox\bgroup % vbox has better behavior than vtop herev
 
8437
  \fi\fi
 
8438
  %
 
8439
  \ifimagevmode
8343
8440
    \nobreak\medskip
8344
8441
    % Usually we'll have text after the image which will insert
8345
8442
    % \parskip glue, so insert it here too to equalize the space
8349
8446
  \fi
8350
8447
  %
8351
8448
  % Leave vertical mode so that indentation from an enclosing
8352
 
  % environment such as @quotation is respected.  On the other hand, if
8353
 
  % it's at the top level, we don't want the normal paragraph indentation.
8354
 
  \noindent
 
8449
  %  environment such as @quotation is respected.
 
8450
  % However, if we're at the top level, we don't want the
 
8451
  %  normal paragraph indentation.
 
8452
  % On the other hand, if we are in the case of @center @image, we don't
 
8453
  %  want to start a paragraph, which will create a hsize-width box and
 
8454
  %  eradicate the centering.
 
8455
  \ifx\centersub\centerV\else \noindent \fi
8355
8456
  %
8356
8457
  % Output the image.
8357
8458
  \ifpdf
8363
8464
    \epsfbox{#1.eps}%
8364
8465
  \fi
8365
8466
  %
8366
 
  \ifimagevmode \medskip \fi  % space after the standalone image
 
8467
  \ifimagevmode
 
8468
    \medskip  % space after a standalone image
 
8469
  \fi  
 
8470
  \ifx\centersub\centerV \egroup \fi
8367
8471
\endgroup}
8368
8472
 
8369
8473