comparison man/texinfo.tex @ 49600:23a1cea22d13

Trailing whitespace deleted.

49599:5ade352e8d1c

%     (and all GNU mirrors, see http://www.gnu.org/order/ftp.html)
%   ftp://texinfo.org/texinfo/texinfo.tex
%   ftp://tug.org/tex/texinfo.tex
%     (and all CTAN mirrors, see http://www.ctan.org),
%   and /home/gd/gnu/doc/texinfo.tex on the GNU machines.
% 
% The texinfo.tex in any given Texinfo distribution could well be out
% of date, so if that's what you're using, please check.
% 
% Texinfo has a small home page at http://texinfo.org/ and also
% http://www.gnu.org/software/texinfo.
%
% Send bug reports to [e-mail].  Please include including a
% complete document in each bug report with which we can reproduce the

}%
\fi

% add check for \lastpenalty to plain's definitions.  If the last thing
% we did was a \nobreak, we don't want to insert more space.
% 
\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount
  \removelastskip\penalty-50\smallskip\fi\fi}
\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount
  \removelastskip\penalty-100\medskip\fi\fi}
\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount

\def\inrightmargin{\doinmargin r}
%
% @inmargin{TEXT [, RIGHT-TEXT]}
% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right;
% else use TEXT for both).
% 
\def\inmargin#1{\parseinmargin #1,,\finish}
\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing.
  \setbox0 = \hbox{\ignorespaces #2}% 
  \ifdim\wd0 > 0pt
    \def\lefttext{#1}%  have both texts
    \def\righttext{#2}%
  \else
    \def\lefttext{#1}%  have only one text

\let\c=\comment

% @paragraphindent NCHARS
% We'll use ems for NCHARS, close enough.
% We cannot implement @paragraphindent asis, though.
% 
\def\asisword{asis} % no translation, these are keywords
\def\noneword{none}
%
\def\paragraphindent{\parsearg\doparagraphindent}
\def\doparagraphindent#1{%

% @math outputs its argument in math mode.
% We don't use $'s directly in the definition of \math because we need
% to set catcodes according to plain TeX first, to allow for subscripts,
% superscripts, special math chars, etc.
% 
% @math does not do math typesetting in section titles, index
% entries, and other such contexts where the catcodes are set before
% @math gets a chance to work.  This could perhaps be fixed, but for now
% at least we can have real math in the main text, where it's needed most.
%

%
% One complication: _ usually means subscripts, but it could also mean
% an actual _ character, as in @math{@var{some_variable} + 1}.  So make
% _ within @math be active (mathcode "8000), and distinguish by seeing
% if the current family is \slfam, which is what @var uses.
% 
{\catcode95 = \active  % 95 = _
\gdef\mathunderscore{%
  \catcode95=\active
  \def_{\ifnum\fam=\slfam \_\else\sb\fi}%
}}
%
% Another complication: we want \\ (and @\) to output a \ character.
% FYI, plain.tex uses \\ as a temporary control sequence (why?), but
% this is not advertised and we don't care.  Texinfo does not
% otherwise define @\.
% 
% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\.
\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi}
%
\def\math{%
  \tex

    \advance\tempnum by1
    \expandafter\xdef\csname#1\endcsname{\the\tempnum}}
  \def\pdfmakeoutlines{{%
    \openin 1 \jobname.toc
    \ifeof 1\else\begingroup
      \closein 1 
      \indexnofonts
      \def\tt{}
      \let\_ = \normalunderscore
      % Thanh's hack / proper braces in bookmarks  
      \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace
      \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace
      %
      \def\chapentry ##1##2##3{}
      \let\appendixentry = \chapentry

      \let\nextmakelinks=\relax
    \else
      \let\nextmakelinks=\makelinks
      \ifnum\lnkcount>0,\fi
      \picknum{#1}%
      \startlink attr{/Border [0 0 0]} 
        goto name{\pdfmkpgn{\the\pgn}}%
      \linkcolor #1%
      \advance\lnkcount by 1%
      \endlink
    \fi

  \def\maketoks{%
    \expandafter\poptoks\the\toksA|ENDTOKS|
    \ifx\first0\adn0
    \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3
    \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6
    \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9 
    \else
      \ifnum0=\countA\else\makelink\fi
      \ifx\first.\let\next=\done\else
        \let\next=\maketoks
        \addtokens{\toksB}{\the\toksD}

  \endlink
\endgroup}

% rms does not like angle brackets --karl, 17may97.
% So now @email is just like @uref, unless we are pdf.
% 
%\def\email#1{\angleleft{\tt #1}\angleright}
\ifpdf
  \def\email#1{\doemail#1,,\finish}
  \def\doemail#1,#2,#3\finish{\begingroup
    \unsepspaces

}


% @synindex foo bar    makes index foo feed into index bar.
% Do this instead of @defindex foo if you don't want it as a separate index.
% 
% @syncodeindex foo bar   similar, but put all entries made for index foo
% inside @code.
% 
\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}}
\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}}

% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo),
% #3 the target index (bar).

\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}}

% Take care of texinfo commands likely to appear in an index entry.
% (Must be a way to avoid doing expansion at all, and thus not have to
% laboriously list every single command here.)
% 
\def\indexdummies{%
\def\ { }%
\def\@{@}% change to @@ when we switch to @ as escape char in aux files.
% Need these in case \tex is in effect and \{ is a \delimiter again.
% But can't use \lbracecmd and \rbracecmd because texindex assumes
% braces and backslashes are used only as delimiters.  
\let\{ = \mylbrace
\let\} = \myrbrace
\def\_{{\realbackslash _}}%
\normalturnoffactive
%

  %
  \hsize = \doublecolumnhsize
  \wd0=\hsize \wd2=\hsize
  \hbox to\pagewidth{\box0\hfil\box2}%
}
% 
% All done with double columns.
\def\enddoublecolumns{%
  \output = {%
    % Split the last of the double-column material.  Leave it on the
    % current page, no automatic page break.

\message{environments,}
% @foo ... @end foo.

% @point{}, @result{}, @expansion{}, @print{}, @equiv{}.
% 
% Since these characters are used in examples, it should be an even number of
% \tt widths. Each \tt character is 1en, so two makes it 1em.
%
\def\point{$\star$}
\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}}

\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}}
\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}}

% The @error{} command.
% Adapted from the TeXbook's \boxit.
% 
\newbox\errorbox
%
{\tentt \global\dimen0 = 3em}% Width of the box.
\dimen2 = .55pt % Thickness of rules
% The text. (`r' is open on the right, `e' somewhat less so on the left.)

  \fi
}


% LaTeX-like @verbatim...@end verbatim and @verb{<char>...<char>}
% If we want to allow any <char> as delimiter, 
% we need the curly braces so that makeinfo sees the @verb command, eg:
% `@verbx...x' would look like the '@verbx' command.  [e-mail]
%
% [Knuth]: Donald Ervin Knuth, 1996.  The TeXbook.
%

  % must do in this order:
  \obeylines \uncatcodespecials \sepspaces
  \everypar{\starttabbox}%
}

% Do the @verb magic: verbatim text is quoted by unique 
% delimiter characters.  Before first delimiter expect a 
% right brace, after last delimiter expect closing brace:
%
%    \def\doverb'{'<char>#1<char>'}'{#1}
%
% [Knuth] p. 382; only eat outer {}

% Do the @verbatim magic: define the macro \doverbatim so that
% the (first) argument ends when '@end verbatim' is reached, ie:
%
%     \def\doverbatim#1@end verbatim{#1}
%
% For Texinfo it's a lot easier than for LaTeX, 
% because texinfo's \verbatim doesn't stop at '\end{verbatim}':
% we need not redefine '\', '{' and '}'
%
% Inspired by LaTeX's verbatim command set [latex.ltx]
%% Include LaTeX hack for completeness -- never know

  \endgroup\nonfillfinish\endgroup
}

% @copying ... @end copying.
% Save the text away for @insertcopying later.
% 
\newbox\copyingbox
%
\def\copying{\begingroup
  \parindent = 0pt  % looks wrong on title page
  \def\Ecopying{\egroup\endgroup}%
  \global\setbox\copyingbox = \vbox\bgroup
}

% @insertcopying.
% 
\def\insertcopying{\unvcopy\copyingbox}


\message{defuns,}
% @defun etc.

% Common pieces to start any @def...
% #1 is the \E... control sequence to end the definition (which we define).
% #2 is the \...x control sequence (which our caller defines).
% #3 is the control sequence to process the header, such as \defunheader.
% 
\def\parsebodycommon#1#2#3{%
  \begingroup\inENV
  % If there are two @def commands in a row, we'll have a \nobreak,
  % which is there to keep the function description together with its
  % header.  But if there's nothing but headers, we want to allow a

% extra argument at the beginning which is the `category', instead of it
% being the hardwired string `Method' or `Instance Variable'.  We have
% to account for this both in the \...x definition and in parsing the
% input at hand.  Thus also need a control sequence (passed as #5) for
% the \E... definition to assign the category name to.
% 
\def\deftypeopparsebody#1#2#3#4#5 #6 {%
  \parsebodycommon{#1}{#2}{#3}%
  \def#2##1 ##2 ##3 {%
    \def#4{##1}%
    \begingroup\obeylines\activeparens\spacesplit{#3{##2}{##3}}}%

\def\deftpheader #1#2#3{\doind {tp}{\code{#2}}%
\begingroup\defname {#2}{#1}\deftpargs{#3}\endgroup}

% These definitions are used if you use @defunx (etc.)
% anywhere other than immediately after a @defun or @defunx.
% 
\def\defcvx#1 {\errmessage{@defcvx in invalid context}}
\def\deffnx#1 {\errmessage{@deffnx in invalid context}}
\def\defivarx#1 {\errmessage{@defivarx in invalid context}}
\def\defmacx#1 {\errmessage{@defmacx in invalid context}}
\def\defmethodx#1 {\errmessage{@defmethodx in invalid context}}

  \ifvmode
    \imagevmodetrue
    \nobreak\bigskip
    % Usually we'll have text after the image which will insert
    % \parskip glue, so insert it here too to equalize the space
    % above and below. 
    \nobreak\vskip\parskip
    \nobreak
    \line\bgroup\hss
  \fi
  %

  \parindent = \defaultparindent
  \setemergencystretch
}

% Use `small' versions.
% 
\def\smallenvironments{%
  \let\smalldisplay = \smalldisplayx
  \let\smallexample = \smalllispx
  \let\smallformat = \smallformatx
  \let\smalllisp = \smalllispx

}

% Say @foo, not \foo, in error messages.
@escapechar = `@@

% These look ok in all fonts, so just make them not special.  
@catcode`@& = @other
@catcode`@# = @other
@catcode`@% = @other

@c Set initial fonts.

49600:23a1cea22d13

%     (and all GNU mirrors, see http://www.gnu.org/order/ftp.html)
%   ftp://texinfo.org/texinfo/texinfo.tex
%   ftp://tug.org/tex/texinfo.tex
%     (and all CTAN mirrors, see http://www.ctan.org),
%   and /home/gd/gnu/doc/texinfo.tex on the GNU machines.
%
% The texinfo.tex in any given Texinfo distribution could well be out
% of date, so if that's what you're using, please check.
%
% Texinfo has a small home page at http://texinfo.org/ and also
% http://www.gnu.org/software/texinfo.
%
% Send bug reports to [e-mail].  Please include including a
% complete document in each bug report with which we can reproduce the

}%
\fi

% add check for \lastpenalty to plain's definitions.  If the last thing
% we did was a \nobreak, we don't want to insert more space.
%
\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount
  \removelastskip\penalty-50\smallskip\fi\fi}
\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount
  \removelastskip\penalty-100\medskip\fi\fi}
\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount

\def\inrightmargin{\doinmargin r}
%
% @inmargin{TEXT [, RIGHT-TEXT]}
% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right;
% else use TEXT for both).
%
\def\inmargin#1{\parseinmargin #1,,\finish}
\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing.
  \setbox0 = \hbox{\ignorespaces #2}%
  \ifdim\wd0 > 0pt
    \def\lefttext{#1}%  have both texts
    \def\righttext{#2}%
  \else
    \def\lefttext{#1}%  have only one text

\let\c=\comment

% @paragraphindent NCHARS
% We'll use ems for NCHARS, close enough.
% We cannot implement @paragraphindent asis, though.
%
\def\asisword{asis} % no translation, these are keywords
\def\noneword{none}
%
\def\paragraphindent{\parsearg\doparagraphindent}
\def\doparagraphindent#1{%

% @math outputs its argument in math mode.
% We don't use $'s directly in the definition of \math because we need
% to set catcodes according to plain TeX first, to allow for subscripts,
% superscripts, special math chars, etc.
%
% @math does not do math typesetting in section titles, index
% entries, and other such contexts where the catcodes are set before
% @math gets a chance to work.  This could perhaps be fixed, but for now
% at least we can have real math in the main text, where it's needed most.
%

%
% One complication: _ usually means subscripts, but it could also mean
% an actual _ character, as in @math{@var{some_variable} + 1}.  So make
% _ within @math be active (mathcode "8000), and distinguish by seeing
% if the current family is \slfam, which is what @var uses.
%
{\catcode95 = \active  % 95 = _
\gdef\mathunderscore{%
  \catcode95=\active
  \def_{\ifnum\fam=\slfam \_\else\sb\fi}%
}}
%
% Another complication: we want \\ (and @\) to output a \ character.
% FYI, plain.tex uses \\ as a temporary control sequence (why?), but
% this is not advertised and we don't care.  Texinfo does not
% otherwise define @\.
%
% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\.
\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi}
%
\def\math{%
  \tex

    \advance\tempnum by1
    \expandafter\xdef\csname#1\endcsname{\the\tempnum}}
  \def\pdfmakeoutlines{{%
    \openin 1 \jobname.toc
    \ifeof 1\else\begingroup
      \closein 1
      \indexnofonts
      \def\tt{}
      \let\_ = \normalunderscore
      % Thanh's hack / proper braces in bookmarks
      \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace
      \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace
      %
      \def\chapentry ##1##2##3{}
      \let\appendixentry = \chapentry

      \let\nextmakelinks=\relax
    \else
      \let\nextmakelinks=\makelinks
      \ifnum\lnkcount>0,\fi
      \picknum{#1}%
      \startlink attr{/Border [0 0 0]}
        goto name{\pdfmkpgn{\the\pgn}}%
      \linkcolor #1%
      \advance\lnkcount by 1%
      \endlink
    \fi

  \def\maketoks{%
    \expandafter\poptoks\the\toksA|ENDTOKS|
    \ifx\first0\adn0
    \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3
    \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6
    \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9
    \else
      \ifnum0=\countA\else\makelink\fi
      \ifx\first.\let\next=\done\else
        \let\next=\maketoks
        \addtokens{\toksB}{\the\toksD}

  \endlink
\endgroup}

% rms does not like angle brackets --karl, 17may97.
% So now @email is just like @uref, unless we are pdf.
%
%\def\email#1{\angleleft{\tt #1}\angleright}
\ifpdf
  \def\email#1{\doemail#1,,\finish}
  \def\doemail#1,#2,#3\finish{\begingroup
    \unsepspaces

}


% @synindex foo bar    makes index foo feed into index bar.
% Do this instead of @defindex foo if you don't want it as a separate index.
%
% @syncodeindex foo bar   similar, but put all entries made for index foo
% inside @code.
%
\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}}
\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}}

% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo),
% #3 the target index (bar).

\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}}

% Take care of texinfo commands likely to appear in an index entry.
% (Must be a way to avoid doing expansion at all, and thus not have to
% laboriously list every single command here.)
%
\def\indexdummies{%
\def\ { }%
\def\@{@}% change to @@ when we switch to @ as escape char in aux files.
% Need these in case \tex is in effect and \{ is a \delimiter again.
% But can't use \lbracecmd and \rbracecmd because texindex assumes
% braces and backslashes are used only as delimiters.
\let\{ = \mylbrace
\let\} = \myrbrace
\def\_{{\realbackslash _}}%
\normalturnoffactive
%

  %
  \hsize = \doublecolumnhsize
  \wd0=\hsize \wd2=\hsize
  \hbox to\pagewidth{\box0\hfil\box2}%
}
%
% All done with double columns.
\def\enddoublecolumns{%
  \output = {%
    % Split the last of the double-column material.  Leave it on the
    % current page, no automatic page break.

\message{environments,}
% @foo ... @end foo.

% @point{}, @result{}, @expansion{}, @print{}, @equiv{}.
%
% Since these characters are used in examples, it should be an even number of
% \tt widths. Each \tt character is 1en, so two makes it 1em.
%
\def\point{$\star$}
\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}}

\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}}
\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}}

% The @error{} command.
% Adapted from the TeXbook's \boxit.
%
\newbox\errorbox
%
{\tentt \global\dimen0 = 3em}% Width of the box.
\dimen2 = .55pt % Thickness of rules
% The text. (`r' is open on the right, `e' somewhat less so on the left.)

  \fi
}


% LaTeX-like @verbatim...@end verbatim and @verb{<char>...<char>}
% If we want to allow any <char> as delimiter,
% we need the curly braces so that makeinfo sees the @verb command, eg:
% `@verbx...x' would look like the '@verbx' command.  [e-mail]
%
% [Knuth]: Donald Ervin Knuth, 1996.  The TeXbook.
%

  % must do in this order:
  \obeylines \uncatcodespecials \sepspaces
  \everypar{\starttabbox}%
}

% Do the @verb magic: verbatim text is quoted by unique
% delimiter characters.  Before first delimiter expect a
% right brace, after last delimiter expect closing brace:
%
%    \def\doverb'{'<char>#1<char>'}'{#1}
%
% [Knuth] p. 382; only eat outer {}

% Do the @verbatim magic: define the macro \doverbatim so that
% the (first) argument ends when '@end verbatim' is reached, ie:
%
%     \def\doverbatim#1@end verbatim{#1}
%
% For Texinfo it's a lot easier than for LaTeX,
% because texinfo's \verbatim doesn't stop at '\end{verbatim}':
% we need not redefine '\', '{' and '}'
%
% Inspired by LaTeX's verbatim command set [latex.ltx]
%% Include LaTeX hack for completeness -- never know

  \endgroup\nonfillfinish\endgroup
}

% @copying ... @end copying.
% Save the text away for @insertcopying later.
%
\newbox\copyingbox
%
\def\copying{\begingroup
  \parindent = 0pt  % looks wrong on title page
  \def\Ecopying{\egroup\endgroup}%
  \global\setbox\copyingbox = \vbox\bgroup
}

% @insertcopying.
%
\def\insertcopying{\unvcopy\copyingbox}


\message{defuns,}
% @defun etc.

% Common pieces to start any @def...
% #1 is the \E... control sequence to end the definition (which we define).
% #2 is the \...x control sequence (which our caller defines).
% #3 is the control sequence to process the header, such as \defunheader.
%
\def\parsebodycommon#1#2#3{%
  \begingroup\inENV
  % If there are two @def commands in a row, we'll have a \nobreak,
  % which is there to keep the function description together with its
  % header.  But if there's nothing but headers, we want to allow a

% extra argument at the beginning which is the `category', instead of it
% being the hardwired string `Method' or `Instance Variable'.  We have
% to account for this both in the \...x definition and in parsing the
% input at hand.  Thus also need a control sequence (passed as #5) for
% the \E... definition to assign the category name to.
%
\def\deftypeopparsebody#1#2#3#4#5 #6 {%
  \parsebodycommon{#1}{#2}{#3}%
  \def#2##1 ##2 ##3 {%
    \def#4{##1}%
    \begingroup\obeylines\activeparens\spacesplit{#3{##2}{##3}}}%

\def\deftpheader #1#2#3{\doind {tp}{\code{#2}}%
\begingroup\defname {#2}{#1}\deftpargs{#3}\endgroup}

% These definitions are used if you use @defunx (etc.)
% anywhere other than immediately after a @defun or @defunx.
%
\def\defcvx#1 {\errmessage{@defcvx in invalid context}}
\def\deffnx#1 {\errmessage{@deffnx in invalid context}}
\def\defivarx#1 {\errmessage{@defivarx in invalid context}}
\def\defmacx#1 {\errmessage{@defmacx in invalid context}}
\def\defmethodx#1 {\errmessage{@defmethodx in invalid context}}

  \ifvmode
    \imagevmodetrue
    \nobreak\bigskip
    % Usually we'll have text after the image which will insert
    % \parskip glue, so insert it here too to equalize the space
    % above and below.
    \nobreak\vskip\parskip
    \nobreak
    \line\bgroup\hss
  \fi
  %

  \parindent = \defaultparindent
  \setemergencystretch
}

% Use `small' versions.
%
\def\smallenvironments{%
  \let\smalldisplay = \smalldisplayx
  \let\smallexample = \smalllispx
  \let\smallformat = \smallformatx
  \let\smalllisp = \smalllispx

}

% Say @foo, not \foo, in error messages.
@escapechar = `@@

% These look ok in all fonts, so just make them not special.
@catcode`@& = @other
@catcode`@# = @other
@catcode`@% = @other

@c Set initial fonts.