texinfo ChangeLog NEWS doc/texinfo.tex doc/texi...

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       11/05/23 23:35:52

Modified files:
        .              : ChangeLog NEWS 
        doc            : texinfo.tex texinfo.txi 
        doc/refcard    : txirefcard-a4.pdf txirefcard.pdf txirefcard.tex 

Log message:
        @deftypefnnewline user option for return types on their own lines

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1240&r2=1.1241
http://cvs.savannah.gnu.org/viewcvs/texinfo/NEWS?cvsroot=texinfo&r1=1.201&r2=1.202
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.tex?cvsroot=texinfo&r1=1.346&r2=1.347
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.380&r2=1.381
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/refcard/txirefcard-a4.pdf?cvsroot=texinfo&rev=1.10
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/refcard/txirefcard.pdf?cvsroot=texinfo&rev=1.10
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/refcard/txirefcard.tex?cvsroot=texinfo&r1=1.17&r2=1.18

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1240
retrieving revision 1.1241
diff -u -b -r1.1240 -r1.1241
--- ChangeLog   23 May 2011 21:53:11 -0000      1.1240
+++ ChangeLog   23 May 2011 23:35:51 -0000      1.1241
@@ -1,4 +1,12 @@
-2011-05-22  Jonathan Nieder  <address@hidden>  (tiny change)
+2011-05-23  Karl Berry  <address@hidden>
+
+       * doc/texinfo.tex (\deftypefnnewline): rename layout option.
+       * NEWS,
+       * doc/refcard/txirefcard.tex,
+       * doc/texinfo.txi (Typed Functions),
+       (Object-Oriented Methods): document @deftypefnnewline.  
+
+2011-05-23  Jonathan Nieder  <address@hidden>  (tiny change)
 
        * util/texi2dvi (local): wrap the fallback definition using eval, to
        hide it from shells, like dash after "[VAR] Do not poplocalvars

Index: NEWS
===================================================================
RCS file: /sources/texinfo/texinfo/NEWS,v
retrieving revision 1.201
retrieving revision 1.202
diff -u -b -r1.201 -r1.202
--- NEWS        24 Feb 2011 17:20:38 -0000      1.201
+++ NEWS        23 May 2011 23:35:51 -0000      1.202
@@ -1,4 +1,4 @@
-$Id: NEWS,v 1.201 2011/02/24 17:20:38 karl Exp $
+$Id: NEWS,v 1.202 2011/05/23 23:35:51 karl Exp $
 This NEWS file records noteworthy changes, very tersely.
 See the manual for detailed information.
 
@@ -26,12 +26,13 @@
 * Language:
   . new command @part for a group of chapters.
   . new environments @raggedright and @smallquotation.
+  . new commands @codequoteundirected and @codequotebacktick, for a
+    better interface than the @set variables.
+  . new commands @deftypefnnewline to print return types on their own lines.
   . new command @headitemfont for the sake of template rows.
   . new command @urefbreakstyle to control breaking of @url/@uref in TeX.
   . new command @xrefautomaticsectiontitle to allow using section titles
     in cross references by default, instead of node names.
-  . new commands @codequoteundirected and @codequotebacktick, for a
-    better interface than the @set variables.
   . new diacritic command @ogonek.
   . new commands for Icelandic letters eth and thorn: @DH{} @dh{} @TH{} @th{}.
   . DEL (0x7f = 0177 = 127) is a true comment character (catcode 14 in TeX).

Index: doc/texinfo.tex
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.tex,v
retrieving revision 1.346
retrieving revision 1.347
diff -u -b -r1.346 -r1.347
--- doc/texinfo.tex     21 May 2011 23:04:12 -0000      1.346
+++ doc/texinfo.tex     23 May 2011 23:35:51 -0000      1.347
@@ -3,7 +3,7 @@
 % Load plain if necessary, i.e., if running under initex.
 \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
 %
-\def\texinfoversion{2011-05-21.16}
+\def\texinfoversion{2011-05-23.16}
 %
 % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
 % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
@@ -6769,11 +6769,11 @@
 \newif\ifdoingtypefn       % doing typed function?
 \newif\ifrettypeownline    % typeset return type on its own line?
 
-% @deftypefnnl on|off says whether the return type of typed functions
-% are printed on their own line.  This affects @deftypefn, @deftypeop,
-% and @deftypemethod.
+% @deftypefnnewline on|off says whether the return type of typed functions
+% are printed on their own line.  This affects @deftypefn, @deftypefun,
+% @deftypeop, and @deftypemethod.
 % 
-\parseargdef\deftypefnnl{%
+\parseargdef\deftypefnnewline{%
   \def\temp{#1}%
   \ifx\temp\onword
     \expandafter\let\csname SETtxideftypefnnl\endcsname

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.380
retrieving revision 1.381
diff -u -b -r1.380 -r1.381
--- doc/texinfo.txi     30 Apr 2011 15:52:30 -0000      1.380
+++ doc/texinfo.txi     23 May 2011 23:35:51 -0000      1.381
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.380 2011/04/30 15:52:30 pertusus Exp $
address@hidden $Id: texinfo.txi,v 1.381 2011/05/23 23:35:51 karl Exp $
 @c Ordinarily, Texinfo files have the extension .texi.  But texinfo.texi
 @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
 
@@ -12738,9 +12738,12 @@
 @node Typed Functions
 @subsection Functions in Typed Languages
 
address@hidden Typed functions
address@hidden Functions, in typed languages
+
 The @code{@@deftypefn} command and its variations are for describing
-functions in languages in which you must declare types of variables and
-functions, such as C and C++.
+functions in languages in which you must declare types of variables
+and functions, such as C and C++.
 
 @table @code
 @findex deftypefn
@@ -12750,7 +12753,7 @@
 typed.  The @code{@@deftypefn} command is written at the beginning of
 a line and is followed on the same line by the category of entity
 being described, the type of the returned value, the name of this
-particular entity, and its arguments, if address@hidden
+particular entity, and its arguments, if any.
 
 @need 800
 @noindent
@@ -12768,7 +12771,7 @@
 @need 1000
 @noindent
 (where the text before the address@hidden'', shown above as two lines, would
-actually be a single line in a real Texinfo file) produces the following
+normally be a single line in a real Texinfo file) produces the following
 in Info:
 
 @smallexample
@@ -12790,19 +12793,18 @@
 
 This means that @code{foobar} is a ``library function'' that returns an
 @code{int}, and its arguments are @var{foo} (an @code{int}) and
address@hidden (a @code{float})address@hidden
address@hidden (a @code{float}).
 
 Since in typed languages, the actual names of the arguments are
 typically scattered among data type names and keywords, Texinfo cannot
-find them without help.  You can either (a)@tie{}write everything
-as straight text, and it will be printed in slanted type; (b)@tie{}use
address@hidden@@var} for the variable names, which will uppercase the
-variable names in Info and use the slanted typewriter font in printed
-output; (c)@tie{}use @code{@@var} for the variable names and
address@hidden@@code} for the type names and keywords, which will be dutifully
-obeyed.
+find them without help.  You can either (a)@tie{}write everything as
+straight text, and it will be printed in slanted type; (b)@tie{}use
address@hidden@@var} for the variable names, which will uppercase the variable
+names in Info and use the slanted typewriter font in printed output;
+(c)@tie{}use @code{@@var} for the variable names and @code{@@code} for
+the type names and keywords, which will be dutifully obeyed.
 
-The template for @code{@@deftypefn} is:@refill
+The template for @code{@@deftypefn} is:
 
 @example
 @group
@@ -12814,7 +12816,7 @@
 
 @noindent
 Note that if the @var{category} or @var{data type} is more than one
-word then it must be enclosed in braces to make it a single address@hidden
+word then it must be enclosed in braces to make it a single argument.
 
 If you are describing a procedure in a language that has packages,
 such as Ada, you might consider using @code{@@deftypefn} in a manner
@@ -12832,14 +12834,14 @@
 @end example
 
 @noindent
-(The @code{@@deftypefn} arguments are shown using continuations
+(Here the @code{@@deftypefn} arguments are shown using continuations
 (@pxref{Def Cmd Continuation Lines}), but could be on a single line in
 a real Texinfo file.)
 
 In this instance, the procedure is classified as belonging to the
 package @code{stacks} rather than classified as a `procedure' and its
 data type is described as @code{private}.  (The name of the procedure
-is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
+is @code{push}, and its arguments are @var{s} and @var{n}.)
 
 @code{@@deftypefn} creates an entry in the index of functions for
 @var{name}.
@@ -12863,15 +12865,33 @@
 
 @end table
 
address@hidden Return type, own line for
address@hidden deftypefnnewline
+Ordinarily, the return type is printed on the same line as the
+function name and arguments, as shown above.  In source code, GNU
+style is to put the return type on a line by itself.  So Texinfo
+provides an option to do that: @code{@@deftypefnnewline on}.
+
+This affects typed functions only---not untyped functions, not typed
+variables, etc..  Specifically, it affects the commands in this
+section, and the analogous commands for object-oriented languages,
+namely @code{@@deftypeop} and @code{@@deftypemethod}
+(@pxref{Object-Oriented Methods}).
+
+Specifying @code{@@deftypefnnewline off} reverts to the default.
+
 
 @node Typed Variables
 @subsection Variables in Typed Languages
 
address@hidden Typed variables
address@hidden Variables, in typed languages
+
 Variables in typed languages are handled in a manner similar to
 functions in typed languages.  @xref{Typed Functions}.  The general
 definition command @code{@@deftypevr} corresponds to
 @code{@@deftypefn} and the specialized definition command
address@hidden@@deftypevar} corresponds to @code{@@address@hidden
address@hidden@@deftypevar} corresponds to @code{@@deftypefun}.
 
 @table @code
 @findex deftypevr
@@ -13228,6 +13248,9 @@
 
 @end table
 
+The typed commands are affected by the @code{@@deftypefnnewline}
+option (@pxref{Typed Functions,, Functions in Typed Languages}).
+
 
 @node Def Cmd Conventions
 @section Conventions for Writing Definitions
@@ -14644,13 +14667,15 @@
 @findex alias
 
 The @samp{@@alias} command defines a new command to be just like an
-existing one.  This is useful for defining additional markup names, thus
-preserving semantic information in the input even though the output
-result may be the same.
+existing one.  This is useful for defining additional markup names,
+thus preserving additional semantic information in the input even
+though the output result may be the same.
 
 Write the @samp{@@alias} command on a line by itself, followed by the
 new command name, an equals sign, and the existing command name.
-Whitespace around the equals sign is ignored.  Thus:
+Whitespace around the equals sign is optional and ignored if present.
+Thus:
+
 @example
 @@alias @var{new} = @var{existing}
 @end example
@@ -14667,17 +14692,19 @@
 
 Macros do not always have the same effect as aliases, due to vagaries
 of argument parsing.  Also, aliases are much simpler to define than
-macros.  So the command is not redundant.  (It was also heavily used
-in the Jargon File!)
+macros.  So the command is not redundant.
+
+Unfortunately, it's not possible to alias Texinfo environments; for
+example, @code{@@alias lang=example} is an error.
 
 Aliases must not be recursive, directly or indirectly.
 
 It is not advisable to redefine any @TeX{} primitive, plain @TeX{}, or
 Texinfo command name as an alias.  Unfortunately this is a very large
 set of names, and the possible resulting errors from @TeX{} are
-completely unpredictable.
+unpredictable.
 
address@hidden will accept the same identifiers for alias as it
address@hidden will accept the same identifiers for aliases as it
 does for macro names, that is, alphanumerics and (except as the first
 character) @samp{-}.
 
@@ -21622,6 +21649,11 @@
 entity, and its arguments, if any.  @xref{Definition Commands}, and
 @ref{deffnx,, Def Cmds in Detail}.
 
address@hidden @@deftypefnnewline @var{on-off}
+Specifies whether return types for @code{@@deftypefn} and similar are
+printed on lines by themselves; default is off.  @xref{Typed
+Functions,, Functions in Typed Languages}.
+
 @item @@deftypefun @var{data-type} @var{function-name} @address@hidden
 @itemx @@deftypefunx @var{data-type} @var{function-name} @address@hidden
 Format a description for a function in a typed language.
@@ -23174,7 +23206,7 @@
 (@url{http://www.gnu.org/software/rcs}) version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.380 2011/04/30 15:52:30 pertusus Exp $
+$Id: texinfo.txi,v 1.381 2011/05/23 23:35:51 karl Exp $
 @end example
 (This is useful in all sources that use version control, not just manuals.)
 You may wish to include the @samp{$Id:} comment in the @code{@@copying}
@@ -23253,7 +23285,7 @@
 
 @verbatim
 \input texinfo   @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.380 2011/04/30 15:52:30 pertusus Exp $
address@hidden $Id: texinfo.txi,v 1.381 2011/05/23 23:35:51 karl Exp $
 @comment %**start of header
 @setfilename sample.info
 @include version.texi

Index: doc/refcard/txirefcard-a4.pdf
===================================================================
RCS file: /sources/texinfo/texinfo/doc/refcard/txirefcard-a4.pdf,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -b -r1.9 -r1.10
Binary files /tmp/cvs6ax1LU and /tmp/cvskYQJYO differ

Index: doc/refcard/txirefcard.pdf
===================================================================
RCS file: /sources/texinfo/texinfo/doc/refcard/txirefcard.pdf,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -b -r1.9 -r1.10
Binary files /tmp/cvs0alpEX and /tmp/cvsk7iwSR differ

Index: doc/refcard/txirefcard.tex
===================================================================
RCS file: /sources/texinfo/texinfo/doc/refcard/txirefcard.tex,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -b -r1.17 -r1.18
--- doc/refcard/txirefcard.tex  24 Feb 2011 17:20:38 -0000      1.17
+++ doc/refcard/txirefcard.tex  23 May 2011 23:35:52 -0000      1.18
@@ -1,5 +1,5 @@
 % Texinfo reference card.
-% $Id: txirefcard.tex,v 1.17 2011/02/24 17:20:38 karl Exp $
+% $Id: txirefcard.tex,v 1.18 2011/05/23 23:35:52 karl Exp $
 %
 %**start of header
 % This file can be printed with 1, 2, or 3 columns per page (see below).
@@ -48,9 +48,9 @@
 % Much of the text is based on, and sometimes copied from, the @-Command
 % Summary node in texinfo.txi, written primarily by Bob Chassell.
 
-\def\versionyear{2008}          % year manual was updated
-\def\versionTexinfo{4.13}       % version of Texinfo this manual is for
-\def\year{2008}                 % copyright year
+\def\versionyear{2011}          % year manual was updated
+\def\versionTexinfo{4.13+}      % version of Texinfo this manual is for
+\def\year{2011}                 % copyright year
 
 \def\copyrightnotice{%
 \vskip 1ex plus 1filll\begingroup\small
@@ -856,12 +856,11 @@
 
 \subsection{Paper sizes}
 
-\def\inch{$''$xx}
-The default paper size is \acro{US} letter-size, 8x11\inch.
+The default paper size is \acro{US} letter-size, 8x11in.
 
address@hidden for a 7x9.25\inch\ trim size.}
address@hidden for a 7x9.25in trim size.}
 address@hidden, @afivepaper}{}{Format for A4 and A5 paper sizes.}
address@hidden variant for A4 with more whitespace.}
address@hidden for A4 with more whitespace.}
 address@hidden for A4 in landscape.}
 address@hidden, height}]}{Format for the explicitly given page dimensions, 
\var{width} by \var{height}.}
 
@@ -887,14 +886,15 @@
 document, thus allowing users to easily override the defaults when
 processing the document according to their desires.
 
address@hidden|off}{Use undirected single quote for @code{'}; default off.}
address@hidden|off}{Use backtick (standalone grave accent) for @code{`}; 
default off.}
address@hidden|off}}{Use undirected single quote for \code{'}; default off.}
address@hidden|off}}{Use backtick (standalone grave accent) for \code{`}; 
default off.}
address@hidden|off}}{Put return type on a line by itself; default off.}
 address@hidden example-like environments by \var{indent} number of spaces 
(perhaps 0).}
 address@hidden|none}}{Indent first paragraphs after section headings, or not.}
 address@hidden|off|single|double}}{Turn page headings on or off, specify 
single-sided or double-sided page headings for printing.}
 address@hidden|distinct|example}}{Specify font for address@hidden: normal 
address@hidden font, a distinct (slanted) typewriter font, or a distinct font 
only within address@hidden and similar.}
 address@hidden paragraphs by \var{indent} number of spaces (perhaps 0); 
preserve source file indentation if \var{indent} is the string \code{asis}.}
address@hidden|off|odd}}{Specify whether chapters start on new pages, and if 
so, whether on odd-numbered (right-hand) new pages; also set the page headings 
accordingly.}
address@hidden|off|odd}}{Specify whether chapters start on new pages, and if 
so, whether on odd-numbered (right-hand) new pages; also set page headings 
accordingly.}
 address@hidden|before|none}}{Specify how address@hidden should break at 
special characters; default \code{after}.}