branch master updated: Add pod2texi.texi to the VCS, in case users cannot regenerate it

[Patrice Dumas]

This is an automated email from the git hooks/post-receive script.

pertusus pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new ca4b1d7b6e Add pod2texi.texi to the VCS, in case users cannot 
regenerate it
ca4b1d7b6e is described below

commit ca4b1d7b6e5c88cdf2fa0677d3d1dd9294ed6e27
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Tue Feb 8 15:36:09 2022 +0100

    Add pod2texi.texi to the VCS, in case users cannot regenerate it
---
 doc/pod2texi.texi | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 147 insertions(+)

diff --git a/doc/pod2texi.texi b/doc/pod2texi.texi
new file mode 100644
index 0000000000..6c4feafcb3
--- /dev/null
+++ b/doc/pod2texi.texi
@@ -0,0 +1,147 @@
+@subsection pod2texi
+@anchor{pod2texi}
+
+@subsubheading pod2texi NAME
+@anchor{pod2texi NAME}
+
+pod2texi - convert Pod to Texinfo
+
+@subsubheading pod2texi SYNOPSIS
+@anchor{pod2texi SYNOPSIS}
+
+@verbatim
+  pod2texi [OPTION]... POD...
+@end verbatim
+
+@subsubheading pod2texi DESCRIPTION
+@anchor{pod2texi DESCRIPTION}
+
+Translate Pod file(s) to Texinfo.  There are two basic modes of
+operation.  First, by default, each Pod is translated to a standalone
+Texinfo manual.
+
+Second, if @code{--base-level} is set higher than 0, each Pod is translated
+to a file suitable for @code{@@include}, and one more file with a main menu
+and all the @code{@@include} is generated.
+
+@subsubheading pod2texi OPTIONS
+@anchor{pod2texi OPTIONS}
+
+@table @asis
+@item @strong{--appendix-sections}
+@anchor{pod2texi @strong{--appendix-sections}}
+
+Use appendix sectioning commands (@code{@@appendix}, ...) instead of the
+default numbered sectioning Texinfo @@-commands (@code{@@chapter},
+@code{@@section}, ...).
+
+@item @strong{--base-level}=@emph{NUM|NAME}
+@anchor{pod2texi @strong{--base-level}=@emph{NUM|NAME}}
+
+Sets the level of the @code{head1} commands.  It may be an integer or a
+Texinfo sectioning command (without the @code{@@}): 1 corresponds to the
+@code{@@chapter}/@code{@@unnumbered} level, 2 to the @code{@@section} level, 
and so on.
+The default is 0, meaning that @code{head1} commands are still output as
+chapters, but the output is arranged as a standalone manual.
+
+If the level is not 0, the Pod file is rendered as a fragment of a
+Texinfo manual suitable for @code{@@include}.  In this case, each Pod file
+has an additional sectioning command covering the entire file, one level
+above the @code{--base-level} value.  Therefore, to make each Pod file a
+chapter in a large manual, you should use @code{section} as the base level.
+
+For an example of making Texinfo out of the Perl documentation itself,
+see @code{contrib/perldoc-all} in the Texinfo source distribution, with
+output available at @url{http://www.gnu.org/software/perl/manual}.
+
+@item @strong{--debug}=@emph{NUM}
+@anchor{pod2texi @strong{--debug}=@emph{NUM}}
+
+Set debugging level to @emph{NUM}.
+
+@item @strong{--headings-as-sections}
+@anchor{pod2texi @strong{--headings-as-sections}}
+
+Use headings commands (@code{@@heading}, ...) instead of the
+default numbered sectioning Texinfo @@-commands (@code{@@chapter},
+@code{@@section}, ...). The sectioning command covering the entire
+file output for each Pod file if @strong{--base-level} is not 0 is a
+numbered command.
+
+@item @strong{--help}
+@anchor{pod2texi @strong{--help}}
+
+Display help and exit.
+
+@item @strong{--output}=@emph{NAME}
+@anchor{pod2texi @strong{--output}=@emph{NAME}}
+
+Name for the first manual, or the main manual if there is a main manual.
+Default is to write to standard output.
+
+@item @strong{--no-section-nodes}
+@anchor{pod2texi @strong{--no-section-nodes}}
+
+Use anchors for sections instead of nodes.
+
+@item @strong{--no-fill-section-gaps}
+@anchor{pod2texi @strong{--no-fill-section-gaps}}
+
+Do not fill sectioning gaps with empty @code{@@unnumbered} files.
+Ordinarily, it's good to keep the sectioning hierarchy intact.
+
+@item @strong{--preamble}=@emph{STR}
+@anchor{pod2texi @strong{--preamble}=@emph{STR}}
+
+Insert @emph{STR} as top boilerplate before menu and includes.  If @emph{STR} 
is
+set to @code{-}, read the top boilerplate from the standard input.  The 
default top
+boilerplate is a minimal beginning for a Texinfo document.
+
+@item @strong{--subdir}=@emph{NAME}
+@anchor{pod2texi @strong{--subdir}=@emph{NAME}}
+
+If there is a main manual with include files (each corresponding to
+an input Pod file), then those include files are put in directory @emph{NAME}.
+
+@item @strong{--unnumbered-sections}
+@anchor{pod2texi @strong{--unnumbered-sections}}
+
+Use unnumbered sectioning commands (@code{@@unnumbered}, ...) instead of the
+default numbered sectioning Texinfo @@-commands (@code{@@chapter},
+@code{@@section}, ...).
+
+@item @strong{--top}=@emph{TOP}
+@anchor{pod2texi @strong{--top}=@emph{TOP}}
+
+Name of the @code{@@top} element for the main manual.  May contain Texinfo 
code.
+
+@item @strong{--version}
+@anchor{pod2texi @strong{--version}}
+
+Display version information and exit.
+
+@end table
+
+@subsubheading pod2texi SEE ALSO
+@anchor{pod2texi SEE ALSO}
+
+@ref{,,, Pod-Simple-Texinfo}.  @ref{,,, perlpod}.  The Texinfo manual.
+Texinfo home page: @url{http://www.gnu.org/software/texinfo/}
+
+@subsubheading pod2texi COPYRIGHT
+@anchor{pod2texi COPYRIGHT}
+
+Copyright 2012-2022 Free Software Foundation, Inc.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License,
+or (at your option) any later version.
+
+There is NO WARRANTY, to the extent permitted by law.
+
+@subsubheading pod2texi AUTHOR
+@anchor{pod2texi AUTHOR}
+
+Patrice Dumas <bug-texinfo@@gnu.org>.
+