[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
texinfo ChangeLog NEWS doc/texinfo.txi doc/refc...
From: |
karl |
Subject: |
texinfo ChangeLog NEWS doc/texinfo.txi doc/refc... |
Date: |
Fri, 14 Sep 2012 18:18:07 +0000 |
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}') {
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- texinfo ChangeLog NEWS doc/texinfo.txi doc/refc...,
karl <=