texinfo ChangeLog NEWS doc/texinfo.txi doc/refc...

[karl]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     karl <karl>     12/09/14 18:18:06

Modified files:
        .              : ChangeLog NEWS 
        doc            : texinfo.txi 
        doc/refcard    : txirefcard.tex txicmdcheck 

Log message:
        document @ifcommanddefined and ...notdefined

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1421&r2=1.1422
http://cvs.savannah.gnu.org/viewcvs/texinfo/NEWS?cvsroot=texinfo&r1=1.215&r2=1.216
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.481&r2=1.482
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/refcard/txirefcard.tex?cvsroot=texinfo&r1=1.26&r2=1.27
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/refcard/txicmdcheck?cvsroot=texinfo&r1=1.5&r2=1.6

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1421
retrieving revision 1.1422
diff -u -b -r1.1421 -r1.1422
--- ChangeLog   13 Sep 2012 18:02:57 -0000      1.1421
+++ ChangeLog   14 Sep 2012 18:18:05 -0000      1.1422
@@ -1,3 +1,13 @@
+2012-09-14  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (Inline Conditionals): rename from Inline
+       Conditional Commands.
+       (Testing for Texinfo Commands): new node describing
+       @ifcommanddefined, @ifcommandnotdefined, txicommandconditionals.
+       * doc/refcard/txicmdcheck: handle checking for them.
+       * doc/refcard/txirefcard.tex: list them.
+       * NEWS: likewise.
+
 2012-09-13  Karl Berry  <address@hidden>
 
        * doc/texinfo.txi (Macro Details): yet more sticky points

Index: NEWS
===================================================================
RCS file: /sources/texinfo/texinfo/NEWS,v
retrieving revision 1.215
retrieving revision 1.216
diff -u -b -r1.215 -r1.216
--- NEWS        5 Sep 2012 00:49:41 -0000       1.215
+++ NEWS        14 Sep 2012 18:18:06 -0000      1.216
@@ -1,4 +1,4 @@
-$Id: NEWS,v 1.215 2012/09/05 00:49:41 karl Exp $
+$Id: NEWS,v 1.216 2012/09/14 18:18:06 karl Exp $
 This NEWS file records noteworthy changes, very tersely.
 See the manual for detailed information.
 
@@ -27,10 +27,12 @@
   . Texinfo commands are supported in node names.
   . #line directives are recognized.
   . new commands @inlinefmt and @inlineraw for brace-delimited conditionals.
+  . new conditionals @ifcommanddefined and @ifcommandnotdefined to test
+    if a Texinfo command is available.
   . 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.
+      for a better interface than the @set variables; now respected by @kbd.
   . new command @xrefautomaticsectiontitle to allow using section titles
       in cross references by default, instead of node names.
   . new commands for Texinfo special characters:

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.481
retrieving revision 1.482
diff -u -b -r1.481 -r1.482
--- doc/texinfo.txi     13 Sep 2012 18:02:57 -0000      1.481
+++ doc/texinfo.txi     14 Sep 2012 18:18:06 -0000      1.482
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.481 2012/09/13 18:02:57 karl Exp $
address@hidden $Id: texinfo.txi,v 1.482 2012/09/14 18:18:06 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.
 
@@ -543,7 +543,7 @@
 * Conditional Commands::        Text for a given format.
 * Conditional Not Commands::    Text for any format other than a given one.
 * Raw Formatter Commands::      Using raw formatter commands.
-* Inline Conditional Commands:: Brace-delimited conditional text.
+* Inline Conditionals::         Brace-delimited conditional text.
 * set clear value::             Variable tests and substitutions.
 * Conditional Nesting::         Using conditionals inside conditionals.
 
@@ -7727,11 +7727,11 @@
 @cindex URL, indicating
 
 Use the @code{@@indicateurl} command to indicate a uniform resource
-locator on the World Wide Web.  This is analogous to @code{@@file},
address@hidden@@var}, etc., and is purely for markup purposes.  It does not
-produce a link you can follow in HTML output (use the @code{@@uref}
-command for that, @pxref{uref,, @code{@@uref}}).  It is useful for
-urls which do not actually exist.  For example:
+locator on the World Wide Web.  This is purely for markup purposes and
+does not produce a link you can follow (use the @code{@@url} or
address@hidden@@uref} command for that, @pxref{uref,,@code{@@uref}}).
address@hidden@@indicateurl} is useful for urls which do not actually exist.
+For example:
 
 @example
 For example, the url might be @@address@hidden://example.org/address@hidden
@@ -7743,6 +7743,8 @@
 For example, the url might be @indicateurl{http://example.org/path}.
 @end display
 
+The output from @code{@@indicateurl} is more or less like that of
address@hidden@@samp} (@pxref{samp,,@code{@@samp}}).
 
 @node email
 @subsection @code{@@address@hidden@var{email-address}[, @address@hidden
@@ -10457,9 +10459,9 @@
 
 @code{@@address@hidden@}} also produces a single @samp{@@} character in the
 output.  It does need following braces, as usual for alphabetic
-commands.  In inline conditionals (@pxref{Inline Conditional
-Commands}), it can be necessary to avoid using the literal @samp{@@}
-character in the source (and may be clearer in other contexts).
+commands.  In inline conditionals (@pxref{Inline Conditionals}), it
+can be necessary to avoid using the literal @samp{@@} character in the
+source (and may be clearer in other contexts).
 
 
 @node Inserting Braces
@@ -10477,7 +10479,7 @@
 @code{@@address@hidden@}} and @code{@@address@hidden@}} also produce
 single @address@hidden and @address@hidden characters in the output.  They do 
need
 following braces, as usual for alphabetic commands.  In inline
-conditionals (@pxref{Inline Conditional Commands}), it can be
+conditionals (@pxref{Inline Conditionals}), it can be
 necessary to avoid using literal brace characters in the source (and
 may be clearer in other contexts).
 
@@ -13577,8 +13579,9 @@
 * Conditional Commands::        Text for a given format.
 * Conditional Not Commands::    Text for any format other than a given one.
 * Raw Formatter Commands::      Using raw formatter commands.
-* Inline Conditional Commands:: Brace-delimited conditional text.
+* Inline Conditionals::         Brace-delimited conditional text.
 * set clear value::             Variable tests and substitutions.
+* Testing for Texinfo Commands:: Testing if a Texinfo command is available.
 * Conditional Nesting::         Using conditionals inside conditionals.
 @end menu
 
@@ -13848,11 +13851,11 @@
 in the remainder of the document.
 
 
address@hidden Inline Conditional Commands
address@hidden Inline Conditional Commands: @code{@@inline}, @code{@@inlineraw}
address@hidden Inline Conditionals
address@hidden Inline Conditionals: @code{@@inline}, @code{@@inlineraw}
 @findex inlinefmt
 @findex inlineraw
address@hidden Inline conditional commands
address@hidden Inline conditionals
 @cindex Conditional commands, inline
 @cindex Brace-delimited conditional text
 @cindex Newlines, avoiding in conditionals
@@ -14195,6 +14198,72 @@
 do not need to edit the three sections.
 
 
address@hidden Testing for Texinfo Commands
address@hidden Testing for Texinfo Commands: @code{@@ifcommanddefined}, 
@code{@@ifcommandnotdefined}
+
address@hidden Testing for Texinfo commands
address@hidden Checking for Texinfo commands
address@hidden Texinfo commands, testing for
address@hidden Commands, testing for Texinfo
address@hidden Versions of Texinfo, adapting to
address@hidden Features of Texinfo, adapting to
+
+Occasionally, you may want to arrange for your manual to test if a
+given Texinfo command is available and (presumably) do some sort of
+fallback formatting if not.  There are conditionals
address@hidden@@ifcommanddefined} and @code{@@ifcommandnotdefined} to do this.
+For example:
+
address@hidden
+@@ifcommanddefined node
+Good, @@address@hidden@@@@address@hidden is defined.
+@@end ifcommanddefined
address@hidden example
+
address@hidden will output the expected `Good, @samp{@@node} is defined.'.
+Caveat: the @TeX{} implementation will report internal @TeX{}
+commands, not just Texinfo commands as being ``defined''; the
address@hidden implementation is reliable in this regard, however.
+
address@hidden @file{NEWS} file for Texinfo
+You can check the @file{NEWS} file in the Texinfo source distribution
+and linked from the Texinfo home page
+(@url{http://www.gnu.org/software/texinfo}) to see when a particular
+command was added.
+
+These command-checking conditionals themselves were added in
address@hidden, released in 2012---decades after Texinfo's
+inception.  In order to test if they themselves are available, 
+the predefined flag @code{txicommandconditionals} can be tested, like
+this:
+
address@hidden
+@@ifset txicommandconditionals
+@@ifcommandnotdefined foobarnode
+(Good, @@foobarnode is not defined.)
+@@end ifcommandnotdefined
+@@end ifset
address@hidden example
+
+Since flags (see the previous section) were added early in the
+existence of Texinfo, there is no problem with assuming they are
+available.
+
+We recommend avoiding these tests whenever possible---which is usually
+the case.  For many software packages, it is reasonable for all
+developers to have a given version of Texinfo (or newer) installed,
+and thus no reason to worry about older versions.  (It is simple to
+download and install the Texinfo source; it does not have any
+problematic dependencies.)
+
+The issue of Texinfo versions does not generally arise for end-users.
+With properly distributed packages, users need not process the Texinfo
+manual simply to build and install the package; they can use
+preformatted Info (or other) output files.  This is desirable in
+general, to avoid unnecessary dependencies between packages
+(@pxref{Releases,,, standard, GNU Coding Standards}).
+
+
 @node Conditional Nesting
 @section Conditional Nesting
 @cindex Conditionals, nested
@@ -17272,7 +17341,7 @@
 automatically taking into account the document language.
 
 @item CASE_INSENSITIVE_FILENAMES
-For address@hidden  Construct file names as if the filesystem was case
+For address@hidden  Construct output file names as if the filesystem were case
 insensitive (@pxref{HTML Splitting}).
 
 @item CHAPTER_HEADER_LEVEL
@@ -18943,8 +19012,8 @@
 @cindex HTML cross references
 @cindex Cross references, in HTML output
 
-Cross references between Texinfo manuals in HTML format amount, in the
-end, to a standard HTML @code{<a>} link, but the details are
+Cross references between Texinfo manuals in HTML format become, in the
+end, a standard HTML @code{<a>} link, but the details are
 unfortunately complex.  This section describes the algorithm used in
 detail, so that Texinfo can cooperate with other programs, such as
 @command{texi2html}, by writing mutually compatible HTML files.
@@ -18959,8 +19028,7 @@
 for each node.  (@xref{HTML Splitting}.)
 
 @cindex Dumas, Patrice
-Acknowledgement: this algorithm was primarily devised by Patrice Dumas
-in 2003--04.
+The algorithm was primarily devised by Patrice Dumas in 2003--04.
 
 @menu
 * Link Basics:       HTML Xref Link Basics.
@@ -20549,6 +20617,12 @@
 text.  Pair with @code{@@end ifclear}.  @xref{set clear value, ,
 @code{@@set} @code{@@clear} @code{@@value}}.
 
address@hidden @@ifcommanddefined @var{txicmd}
address@hidden @@ifcommandnotdefined @var{txicmd}
+If the Texinfo code @samp{@@@var{txicmd}} is (not) defined, format the
+follow text.  Pair with the corresponding @code{@@end ifcommand...}.
address@hidden for Texinfo Commands}.
+
 @item @@ifdocbook
 @itemx @@ifhtml
 @itemx @@ifinfo
@@ -20616,7 +20690,7 @@
 @item @@address@hidden@var{fmt}, @address@hidden
 @itemx @@address@hidden@var{fmt}, @address@hidden
 Insert (raw) @var{text} only if the output format is @var{fmt}.
address@hidden Conditional Commands}.
address@hidden Conditionals}.
 
 @item \input @var{macro-definitions-file}
 Use the specified macro definitions file.  This command is used only
@@ -21864,7 +21938,7 @@
 or other version control systems, which expand it into a string such
 as:
 @example
-$Id: texinfo.txi,v 1.481 2012/09/13 18:02:57 karl Exp $
+$Id: texinfo.txi,v 1.482 2012/09/14 18:18:06 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}

Index: doc/refcard/txirefcard.tex
===================================================================
RCS file: /sources/texinfo/texinfo/doc/refcard/txirefcard.tex,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -b -r1.26 -r1.27
--- doc/refcard/txirefcard.tex  24 Apr 2012 18:10:59 -0000      1.26
+++ doc/refcard/txirefcard.tex  14 Sep 2012 18:18:06 -0000      1.27
@@ -1,5 +1,5 @@
 % Texinfo reference card.
-% $Id: txirefcard.tex,v 1.26 2012/04/24 18:10:59 karl Exp $
+% $Id: txirefcard.tex,v 1.27 2012/09/14 18:18:06 karl Exp $
 %
 %**start of header
 % This file can be printed with 1, 2, or 3 columns per page (see below).
@@ -220,6 +220,9 @@
 % inserted.  Using \paralign instead of \halign solves this problem.
 \def\paralign{\vskip\parskip\halign}
 
+% forced line break.
+\def\linebreak{\hfil\break}
+
 % code, samp - typewriter, without or with surrounding quotes.
 \def\code#1{{\tt#1}\null}      %\null so not an abbrev even if period follows
 \def\samp#1{`\code{#1}'}
@@ -398,12 +401,12 @@
 begin with lines like this:
 
 {\advance\baselineskip by -3pt
-\code{\bschar input texinfo}\hfil\break
address@hidden {\sl info-file-name}}\hfil\break
+\code{\bschar input texinfo}\linebreak
address@hidden {\sl info-file-name}}\linebreak
 address@hidden {\sl name-of-manual}}}
 
 \dots the contents of the Texinfo document,
-ending with:\hfil\break
+ending with:\linebreak
 address@hidden
 
 
@@ -628,7 +631,7 @@
 
 \section{Floating displays}
 
address@hidden within which floating material is defined. Pair with 
address@hidden float}.}
address@hidden enclosing material which can float. Pair with address@hidden 
float}.}
 address@hidden a list of floats for a given float type.}
 address@hidden the full caption for a address@hidden anywhere in the float 
environment.}
 address@hidden the short caption for a address@hidden, used in the list of 
floats.}
@@ -838,6 +841,12 @@
 address@hidden address@hidden ifset}}{If the Texinfo variable \var{name} is 
set, format the enclosed text.}
 address@hidden address@hidden ifclear}}{If the Texinfo variable \var{name} is 
not set, format the enclosed text.}
 
+\subsection{Testing for commands}
+
address@hidden address@hidden ifcommanddefined}}{\linebreak Text to appear only 
if address@hidden is defined \dots}
address@hidden address@hidden ifcommandnotdefined}}{\linebreak\dots\ or not 
defined.}
+\txicmd{txicommandconditionals}{}{Texinfo variable predefined to true.}
+
 
 \section{Defining new Texinfo commands}
 
@@ -1015,7 +1024,7 @@
 \infokey C-g         Cancel the current operation.\cr
 \endinfokeys
 
-The Texinfo reference manual is available via \code{info texinfo}\hfil\break
+The Texinfo reference manual is available via \code{info texinfo}\linebreak
 (and at \code{http://www.gnu.org/software/texinfo/manual}).
 
 \copyrightnotice

Index: doc/refcard/txicmdcheck
===================================================================
RCS file: /sources/texinfo/texinfo/doc/refcard/txicmdcheck,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- doc/refcard/txicmdcheck     3 Jan 2012 18:26:58 -0000       1.5
+++ doc/refcard/txicmdcheck     14 Sep 2012 18:18:06 -0000      1.6
@@ -1,5 +1,5 @@
 #!/usr/bin/env perl
-# $Id: txicmdcheck,v 1.5 2012/01/03 18:26:58 karl Exp $
+# $Id: txicmdcheck,v 1.6 2012/09/14 18:18:06 karl Exp $
 # Copyright 2008, 2011, 2012 Free Software Foundation, Inc.
 # 
 # This program is free software; you can redistribute it and/or modify
@@ -89,6 +89,7 @@
     for my $c (@cmds) {
 #warn "refcard $c\n";
 #warn "refcard $c{x}\n" if $xcmd;
+      next if $c eq "txicommandconditionals"; # variable not separate in manual
       if ($c eq '@\tildechar') { # TeX specialties, forcibly make them match
         $c = '@~';
       } elsif ($c eq '@\var{whitespace}') {