[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
texinfo ChangeLog doc/texinfo.txi doc/version-s...
|
From: |
Patrice Dumas |
|
Subject: |
texinfo ChangeLog doc/texinfo.txi doc/version-s... |
|
Date: |
Sat, 17 Jul 2010 21:35:19 +0000 |
CVSROOT: /sources/texinfo
Module name: texinfo
Changes by: Patrice Dumas <pertusus> 10/07/17 21:35:19
Modified files:
. : ChangeLog
doc : texinfo.txi version-stnd.texi version.texi
Log message:
* doc/texinfo.txi (setfilename): explain how file name is
determined
when there is no @setfilename.
(makeinfo options, HTML Translation): document new options and
update according to the changes in behaviour.
Separate --plaintext from --no-headers.
(Pointer Validation): @-commands in nodes are now supported.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1059&r2=1.1060
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.255&r2=1.256
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/version-stnd.texi?cvsroot=texinfo&r1=1.46&r2=1.47
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/version.texi?cvsroot=texinfo&r1=1.79&r2=1.80
Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1059
retrieving revision 1.1060
diff -u -b -r1.1059 -r1.1060
--- ChangeLog 17 Jul 2010 00:05:37 -0000 1.1059
+++ ChangeLog 17 Jul 2010 21:35:18 -0000 1.1060
@@ -1,3 +1,12 @@
+2010-07-17 Patrice Dumas <address@hidden>
+
+ * doc/texinfo.txi (setfilename): explain how file name is determined
+ when there is no @setfilename.
+ (makeinfo options, HTML Translation): document new options and
+ update according to the changes in behaviour.
+ Separate --plaintext from --no-headers.
+ (Pointer Validation): @-commands in nodes are now supported.
+
2010-07-16 Patrice Dumas <address@hidden>
* makeinfo/Makefile.am (noinst_PROGRAMS): no more installation
Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.255
retrieving revision 1.256
diff -u -b -r1.255 -r1.256
--- doc/texinfo.txi 12 Jul 2010 00:34:25 -0000 1.255
+++ doc/texinfo.txi 17 Jul 2010 21:35:18 -0000 1.256
@@ -1,5 +1,5 @@
\input texinfo.tex @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.255 2010/07/12 00:34:25 karl Exp $
address@hidden $Id: texinfo.txi,v 1.256 2010/07/17 21:35:18 pertusus 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.
@@ -882,7 +882,7 @@
@item Plain text
@cindex Plain text output
-(Generated via @command{makeinfo --no-headers}.) This is almost the
+(Generated via @command{makeinfo --plaintext}.) This is almost the
same as Info output, except the navigational control characters are
omitted. Also, standard output is used by default.
@@ -2947,6 +2947,13 @@
with @samp{html}, or add @samp{.html} if the given name has no
extension.
+If there is no @code{@@setfilename}, the output file to be generated
+is based on the input file name. First any extension
+in @code{.texi}, @code{.tex}, @code{.txi} or @code{.texinfo} is removed
+from the input file and then the output format specific extension is
+added (@code{.html} when generating HTML, @code{.info} when generating
+Info, @enddots{}).
+
@pindex texinfo.cnf
The @code{@@setfilename} line produces no output when you typeset a
manual with @TeX{}, but it is nevertheless essential: it opens the
@@ -3167,7 +3174,7 @@
You may wish to include titlepage-like information for plain text
output. Simply place any such leading material between
@code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo}
-includes this when writing plain text (@samp{--no-headers}), along with
+includes this when writing plain text (@samp{--plaintext}), along with
an @code{@@insertcopying}.
@menu
@@ -3615,7 +3622,7 @@
Since an Info file uses menus instead of tables of contents, the Info
formatting commands ignore the contents commands. But the contents are
included in plain text output (generated by @code{makeinfo
---no-headers}), unless @code{makeinfo} is writing its output to standard
+--plaintext}), unless @code{makeinfo} is writing its output to standard
output.
When @code{makeinfo} writes a short table of contents while producing
@@ -5144,9 +5151,7 @@
@item
@@-commands in node names are not allowed. This includes punctuation
characters that are escaped with a @samp{@@}, such as @code{@@} and
address@hidden@{}, and accent commands such as @samp{@@'}. (For a few cases
-when this is useful, Texinfo has limited support for using
address@hidden@@-commands} in node names; see @ref{Pointer Validation}.)
Perhaps
address@hidden@{}, and accent commands such as @samp{@@'}. Perhaps
this limitation will be removed some day.
@item
@@ -5175,6 +5180,9 @@
unnumberedsec appendixsec heading
@end smallexample
+If you really want a comma in a node name, you can use
@code{@@address@hidden@}}.
address@hidden a Comma}.
+
@cindex Case in node name
@item
Case is significant in node names.
@@ -15998,13 +16006,30 @@
Cause the variable @var{var} to be defined. This is equivalent to
@code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
address@hidden --commands-in-node-names
address@hidden --commands-in-node-names
-Allow @code{@@}-commands in node names. This is not recommended, as it
-can probably never be implemented in @TeX{}. It also makes
address@hidden much slower. Also, this option is ignored when
address@hidden is used. @xref{Pointer Validation}, for more
-details.
address@hidden address@hidden
address@hidden address@hidden
+Append @var{dir} to the directory search list for finding customization
+files that may be loaded with @option{--init-file}. By default the following
+directories are searched, in that order (with @var{program_name} the
+name of the program invoked on the command line):
+
address@hidden
address@hidden The current directory @file{.};
address@hidden @file{$HOME/.program_name} where @env{$HOME} is the user home
directory;
address@hidden @file{sysconfdir/program_name} where @file{sysconfdir} is the
directory
+for local configuration, determined at build time;
address@hidden @file{datadir/program_name} where @file{datadir} is the directory
+for data, determined at build time;
address@hidden the directory @file{.texinfo/init} in the current directory;
address@hidden @file{$HOME/.texinfo/init} where @env{$HOME} is the user home
directory;
address@hidden @file{sysconfdir/texinfo/init} with @file{sysconfdir} as above;
address@hidden @file{datadir/texinfo/init} with @file{datadir} as above.
address@hidden enumerate
+
+Note that
address@hidden can actually be a list of several directories separated by the
+usual path separator character (@samp{:} on Unix, @samp{;} on
+MS-DOS/MS-Windows).
@item address@hidden
@opindex --css-include
@@ -16059,7 +16084,7 @@
width. (Filling is the process of breaking up and connecting lines so
that lines are the same length as or shorter than the number specified
as the fill column. Lines are broken between words.) The default value
-is 72. Ignored with @samp{--html}.
+is 72. Only useful when generating Info.
@item address@hidden
@itemx -s @var{style}
@@ -16072,7 +16097,11 @@
footnote style is @samp{separate}, @code{makeinfo} makes a new node
containing the footnotes found in the current node. When the footnote
style is @samp{end}, @code{makeinfo} places the footnote references at
-the end of the current node. Ignored with @samp{--html}.
+the end of the current node.
+
+In HTML, when the footnote style is @samp{end} footnotes are put at
+the end of the file. If set to @samp{separate} they are in a separate
+file if split.
@item --force
@itemx -F
@@ -16121,6 +16150,14 @@
format. For instance, if @option{--iftex} is specified, then
@samp{@@iftex} and @samp{@@tex} blocks will be read.
address@hidden address@hidden
address@hidden address@hidden
+Load @var{file} code to modify the behaviour and output of the generated
+manual. @option{--conf-dir} may be used to add a directory to the list
+of directories where customization files are searched for. It is customary
+to use the @code{.init} extension with customization files, but it is
+not enforced by anything, and the @var{file} file name is taken literally.
+
@item address@hidden
@opindex address@hidden
In HTML mode, output a tab separated file containing three columns:
@@ -16138,30 +16175,22 @@
@command{texi2dvi}.
@item --no-headers
address@hidden --plaintext
@opindex --no-headers
address@hidden --plaintext
address@hidden Plain text output
address@hidden ASCII text output
address@hidden Generating plain text files
address@hidden @file{INSTALL} file, generating
@cindex Node separators, omitting
address@hidden Generating plain text files
@cindex Menus, omitting
-Do not include menus or node separator lines in the output, and
-implicitly @option{--enable-encoding} (see above). This results in a
-simple plain text file that you can (for example) send in email
-without complications, or include in a distribution (as in an
address@hidden file).
+
+Do not include menus or node separator lines in the output. If generating
+Info, in addition, this is the same as using @option{--plaintext},
+resulting in a simple plain text file, ignoring @code{@@setfilename}
+and writing to standard output by default---can be overridden with @option{-o}.
@cindex Navigation links, omitting
-For HTML output, likewise omit menus. And if @samp{--no-split} is also
-specified, do not include a navigation links at the top of each node
-(these are never included in the default case of split output).
+For HTML output, likewise omit menus. If split, output navigation links only
+at the beginning of files. And if @samp{--no-split} is
+specified, do not include a navigation links at the top of each node.
@xref{Generating HTML}.
-In both cases, ignore @code{@@setfilename} and write to standard
-output by default---can be overridden with @option{-o}.
-
@item --no-ifdocbook
@opindex --no-ifdocbook
@itemx --no-ifhtml
@@ -16191,15 +16220,6 @@
Do not output chapter, section, and appendix numbers.
You need to specify this if your manual is not hierarchically-structured.
address@hidden --no-split
address@hidden --no-split
address@hidden Splitting of output files
address@hidden Output file splitting
-Suppress the splitting stage of @code{makeinfo}. By default, large
-output files (where the size is greater than 70k bytes) are split into
-smaller subfiles. For Info output, each one is approximately 50k bytes.
-For HTML output, each file contains one node (@pxref{Generating HTML}).
-
@item --no-pointer-validate
@itemx --no-validate
@opindex --no-pointer-validate
@@ -16215,6 +16235,20 @@
@opindex --no-warn
Suppress warning messages (but @emph{not} error messages).
address@hidden --node-files
address@hidden --no-node-files
address@hidden --node-files
address@hidden --no-node-files
+When generating HTML, produce redirection files for nodes and anchors
+that are not already in the file with name corresponding to the node or
+anchor name (@pxref{HTML Xref Node Name Expansion}). In the default case
+it is set if the manual is split.
+
+If @option{--no-split} is set, @option{--node-files} can ensure that
+redirection files are done. If split at chapter or sections,
address@hidden suppress the output of the redirection files.
address@hidden HTML}.
+
@item --number-sections
@opindex --number-sections
Output chapter, section, and appendix numbers as in printed manuals.
@@ -16227,10 +16261,19 @@
@opindex -o @var{file}
Specify that the output should be directed to @var{file} and not to the
file name specified in the @code{@@setfilename} command found in the
-Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output
-goes to standard output and @samp{--no-split} is implied. For split
-HTML output, @var{file} is the name for the directory into which all
-HTML nodes are written (@pxref{Generating HTML}).
+Texinfo source (@pxref{setfilename}) nor to the output file based on the
+input file name.
+
+If @var{file} is @samp{-}, output
+goes to standard output and @samp{--no-split} is implied.
+
+If @var{file}
+is a directory or ends with a @samp{/} the usual rules are used to determine
+the file name (use @code{@@setfilename} or the input file name) but the
+resulting files are output in the @var{file} directory.
+
+When generating HTML, if output is split, @var{file} is
+the name for the directory into which all files are written.
@item -P @var{dir}
@opindex -P @var{dir}
@@ -16258,6 +16301,60 @@
Indent each paragraph by @var{num} spaces.
@end table
address@hidden --plaintext
address@hidden --plaintext
address@hidden Plain text output
address@hidden ASCII text output
address@hidden Generating plain text files
address@hidden @file{INSTALL} file, generating
address@hidden Node separators, omitting
address@hidden Menus, omitting
+Output a plain text file, do not include menus or node
+separator lines in the output. This results in a
+simple plain text file that you can (for example) send in email
+without complications, or include in a distribution (as in an
address@hidden file).
+
+Ignore @code{@@setfilename} and write to standard
+output by default---can be overridden with @option{-o}.
+
address@hidden --set-init-variable @address@hidden
address@hidden --set-init-variable @address@hidden
+Set the value of the configuration variable @var{var} to be @var{value}.
+Many aspects of the behaviour and output may be modified by modifying
+configuration variables. This allows to go beyond what can be set in
+the document by @@-commands and with command line switches.
+
address@hidden address@hidden
address@hidden --no-split
address@hidden address@hidden
address@hidden --no-split
address@hidden Splitting of output files
address@hidden Output file splitting
+
+When generating Info, @option{--no-split} suppress the splitting stage
+of @code{makeinfo}. By default, large
+output files (where the size is greater than 70k bytes) are split into
+smaller subfiles. For Info output, each one is approximately 50k bytes.
+
+For HTML output, each file contains one node (@pxref{Generating HTML})
+in the default case. With @option{--no-split} the output is not split.
address@hidden may be used to specify at which level the resulting document
+should be split, with @var{split}. The possible values are:
+
address@hidden @samp
address@hidden chapter
+The resulting manual is split at @code{@@chapter} and other sectionning
+@@-commands at this level.
+
address@hidden section
+The resulting manual is split at @code{@@section} and other sectionning
+@@-commands at this level.
+
address@hidden node
+The manual is split at every node. This is the default.
address@hidden table
+
@item address@hidden
@opindex address@hidden
Keep Info files to at most @var{num} characters; default is 300,000.
@@ -16345,54 +16442,6 @@
address@hidden
@end enumerate
address@hidden @@-commands in @@node, limited support
-Some Texinfo documents might fail during the validation phase because
-they use commands like @code{@@value} and @code{@@definfoenclose} in
-node definitions and cross-references inconsistently. (Your best bet
-is to avoid using @@-commands in node names.) Consider the
-following example:
-
address@hidden
address@hidden
-@@set nodename Node 1
-
-@@node @@address@hidden@}, Node 2, Top, Top
-
-This is node 1.
-
-@@node Node 2, , Node 1, Top
-
-This is node 2.
address@hidden group
address@hidden example
-
address@hidden
-Here, the node ``Node 1'' was referenced both verbatim and through
address@hidden@@value}.
-
-By default, @code{makeinfo} fails such cases, because node names are not
-fully expanded until they are written to the output file. You should
-always try to reference nodes consistently; e.g., in the above example,
-the second @code{@@node} line should have also used @code{@@value}.
-However, if, for some reason, you @emph{must} reference node names
-inconsistently, and @code{makeinfo} fails to validate the file, you can
-use the @samp{--commands-in-node-names} option to force @code{makeinfo}
-to perform the expensive expansion of all node names it finds in the
-document. This might considerably slow down the program, though;
-twofold increase in conversion time was measured for large documents
-such as the Jargon file.
-
address@hidden @@value in @@node lines
-The support for @code{@@}-commands in @code{@@node} directives is not
-general enough to be freely used. For example, if the example above
-redefined @code{nodename} somewhere in the document, @code{makeinfo}
-will fail to convert it, even if invoked with the
address@hidden option.
-
address@hidden has no effect if the @samp{--no-validate}
-option is given.
-
-
@node makeinfo in Emacs
@subsection Running @code{makeinfo} Within Emacs
@cindex Running @code{makeinfo} in Emacs
@@ -17237,27 +17286,34 @@
@cindex Navigation bar, in HTML output
By default, a navigation bar is inserted at the start of each node,
-analogous to Info output. The @samp{--no-headers} option suppresses
-this if used with @samp{--no-split}. Header @code{<link>} elements in
+analogous to Info output. If the @samp{--no-headers} option is used,
+navigation bar is only inserted at the beginning of split files. Header
address@hidden<link>} elements in
split output can support info-like navigation with browsers like Lynx
and @w{Emacs W3} which implement this address@hidden feature.
@cindex HTML output, browser compatibility of
-The HTML generated is mostly standard (i.e., address@hidden, RFC-1866).
+The HTML generated is standard address@hidden It also tries to be as
+much as possible compatible with former standards
+(i.e., address@hidden, RFC-1866).
One exception is that address@hidden tables are generated from the
@code{@@multitable} command, but tagged to degrade as well as possible
in browsers without table support. The address@hidden @samp{lang}
-attribute on the @samp{<html>} attribute is also used. (Please report
+attribute on the @samp{<html>} attribute is also used. And entities
+that are not in the address@hidden standard are also used. (Please report
output from an error-free run of @code{makeinfo} which has browser
portability problems as a bug.)
+It is possible to output strict address@hidden output by loading the
address@hidden initialization file.
+
@node HTML Splitting
@section HTML Splitting
@cindex Split HTML output
@cindex HTML output, split
-When splitting output (which is the default), @command{makeinfo}
+When splitting output at nodes (which is the default), @command{makeinfo}
writes HTML output into (generally) one output file per Texinfo source
@code{@@node}.
@@ -17270,6 +17326,13 @@
the same except for case will also be folded into the same output
file.
+It is also possible to split at chapter or section with @option{--split}.
+In that case, the file names are constructed after the name of the
+node associated with the sectionning command. Also, unless
address@hidden is used a redirection file is output for
+every node in order to allow for cross-references to that manual
+(@pxref{HTML Xref}).
+
When splitting, the HTML output files are written into a subdirectory,
with the name chosen as follows:
@enumerate
@@ -17296,8 +17359,8 @@
Monolithic output (@code{--no-split}) is named according to
@code{@@setfilename} (with any @samp{.info} extension is replaced with
address@hidden) or @code{--output} (the argument is used literally).
-
address@hidden), @code{--output} (the argument is used literally), or
+based on the input file name if there is no @code{@@setfilename}.
@node HTML CSS
@section HTML CSS
@@ -17610,13 +17673,10 @@
@cindex HTML cross-reference command expansion
In standard Texinfo, node names may not contain @@-commands.
address@hidden has an option @option{--commands-in-node-names}
-which partially supports it (@pxref{Invoking makeinfo}), but it is not
-robust and not recommended.
-
-Thus, @command{makeinfo} does not fully implement this part of the
-HTML cross-reference algorithm, but it is documented here for the sake
-of completeness.
address@hidden supports @@-commands in node names, but @TeX{}
+might not. Therefore, even if @command{makeinfo} implements
+this part of the HTML cross-reference algorithm, you should still
+avoid using @@-commands in node names.
First, comments are removed.
@@ -19788,7 +19848,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.255 2010/07/12 00:34:25 karl Exp $
+$Id: texinfo.txi,v 1.256 2010/07/17 21:35:18 pertusus 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}
@@ -19867,7 +19927,7 @@
@verbatim
\input texinfo @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.255 2010/07/12 00:34:25 karl Exp $
address@hidden $Id: texinfo.txi,v 1.256 2010/07/17 21:35:18 pertusus Exp $
@comment %**start of header
@setfilename sample.info
@include version.texi
Index: doc/version-stnd.texi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/version-stnd.texi,v
retrieving revision 1.46
retrieving revision 1.47
diff -u -b -r1.46 -r1.47
--- doc/version-stnd.texi 29 Jun 2010 21:46:54 -0000 1.46
+++ doc/version-stnd.texi 17 Jul 2010 21:35:19 -0000 1.47
@@ -1,4 +1,4 @@
@set UPDATED 19 March 2010
@set UPDATED-MONTH March 2010
address@hidden EDITION 4.13
address@hidden VERSION 4.13
address@hidden EDITION 5.0
address@hidden VERSION 5.0
Index: doc/version.texi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/version.texi,v
retrieving revision 1.79
retrieving revision 1.80
diff -u -b -r1.79 -r1.80
--- doc/version.texi 29 Jun 2010 21:46:54 -0000 1.79
+++ doc/version.texi 17 Jul 2010 21:35:19 -0000 1.80
@@ -1,4 +1,4 @@
address@hidden UPDATED 22 June 2010
address@hidden UPDATED-MONTH June 2010
address@hidden EDITION 4.13
address@hidden VERSION 4.13
address@hidden UPDATED 17 July 2010
address@hidden UPDATED-MONTH July 2010
address@hidden EDITION 5.0
address@hidden VERSION 5.0
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- texinfo ChangeLog doc/texinfo.txi doc/version-s...,
Patrice Dumas <=