[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[no subject]
|
From: |
Patrice Dumas |
|
Date: |
Wed, 17 Apr 2024 15:44:45 -0400 (EDT) |
branch: master
commit 07bd757243b0844afe529b24a468d33415d98995
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Wed Apr 17 21:44:36 2024 +0200
* Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm (_accessorize),
(_preamble): add a texinfo_generate_setfilename accessor to determine
if a @setfilename is inserted in standalone manuals.
* Pod-Simple-Texinfo/pod2texi.pl: add a --generate-setfilename option,
pass to the POD parser.
---
ChangeLog | 9 ++
Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm | 48 +++++----
Pod-Simple-Texinfo/pod2texi.pl | 18 +++-
doc/pod2texi.texi | 12 ++-
man/pod2texi.1 | 146 +++++++--------------------
5 files changed, 101 insertions(+), 132 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index e533d1e162..9f749c146e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2024-04-17 Patrice Dumas <pertusus@free.fr>
+
+ * Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm (_accessorize),
+ (_preamble): add a texinfo_generate_setfilename accessor to determine
+ if a @setfilename is inserted in standalone manuals.
+
+ * Pod-Simple-Texinfo/pod2texi.pl: add a --generate-setfilename option,
+ pass to the POD parser.
+
2024-04-17 Patrice Dumas <pertusus@free.fr>
* Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
diff --git a/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
b/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
index 620d6702fb..4f5fef5d4a 100644
--- a/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
+++ b/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
@@ -108,6 +108,7 @@ my @raw_formats = ('html', 'HTML', 'docbook', 'DocBook',
'texinfo',
__PACKAGE__->_accessorize(
'texinfo_add_upper_sectioning_command',
'texinfo_debug',
+ 'texinfo_generate_setfilename', # for standalone manuals
'texinfo_internal_pod_manuals',
'texinfo_man_url_prefix',
'texinfo_main_command_sectioning_style',
@@ -129,6 +130,8 @@ sub new
$new->accept_targets(@raw_formats);
$new->preserve_whitespace(1);
$new->texinfo_debug(0);
+ # TODO set to 0 when the time has come.
+ #$new->texinfo_generate_setfilename(0);
$new->texinfo_section_nodes(0);
$new->texinfo_sectioning_base_level($sectioning_base_level);
$new->texinfo_man_url_prefix($man_url_prefix);
@@ -234,24 +237,26 @@ sub _preamble($)
if ($self->texinfo_sectioning_base_level() == 0) {
#print STDERR "$fh\n";
print $fh '\input texinfo'."\n";
- my $setfilename;
- if (defined($self->texinfo_short_title())) {
- $setfilename = pod_title_to_file_name($self->texinfo_short_title());
- } else {
- my $source_filename = $self->source_filename();
- if (defined($source_filename) and $source_filename ne '') {
- if ($source_filename eq '-') {
- $setfilename = $STDIN_DOCU_NAME;
- } else {
- $setfilename = $source_filename;
- $setfilename =~ s/\.(pod|pm)$//i;
+ if ($self->texinfo_generate_setfilename()) {
+ my $setfilename;
+ if (defined($self->texinfo_short_title())) {
+ $setfilename = pod_title_to_file_name($self->texinfo_short_title());
+ } else {
+ my $source_filename = $self->source_filename();
+ if (defined($source_filename) and $source_filename ne '') {
+ if ($source_filename eq '-') {
+ $setfilename = $STDIN_DOCU_NAME;
+ } else {
+ $setfilename = $source_filename;
+ $setfilename =~ s/\.(pod|pm)$//i;
+ }
}
}
- }
- if (defined($setfilename) and $setfilename =~ m/\S/) {
- $setfilename = protect_text($setfilename, 1, 1);
- $setfilename .= '.info';
- print $fh "\@setfilename $setfilename\n\n"
+ if (defined($setfilename) and $setfilename =~ m/\S/) {
+ $setfilename = protect_text($setfilename, 1, 1);
+ $setfilename .= '.info';
+ print $fh "\@setfilename $setfilename\n\n"
+ }
}
my $title = $self->get_title();
@@ -1151,6 +1156,11 @@ Texinfo obtained from POD is parsed as Texinfo code to
be normalized or
modified and to report associated Texinfo processing errors. More information
output with higher levels. Default 0, no debugging information output.
+=item texinfo_generate_setfilename
+
+If set, generate a C<@setfilename> line in standalone manuals. Ignored
+unless L</texinfo_sectioning_base_level> is 0.
+
=item texinfo_internal_pod_manuals
The argument should be a reference on an array containing the short
@@ -1165,9 +1175,9 @@ Relevant if L</texinfo_sectioning_base_level> is not set
to 0.
=item texinfo_main_command_sectioning_style
Sectioning style for the main command appearing at the beginning of the output
-file if L</texinfo_sectioning_base_level> is anything else than 0. Unset in
the
-default case. If unset, use L</texinfo_sectioning_style>, except for style
-C<heading>, for which the C<numbered> style is used in the default case.
+file if L</texinfo_sectioning_base_level> not 0. Unset in the default case.
+If unset, use L</texinfo_sectioning_style>, except for style C<heading>, for
+which the C<numbered> style is used in the default case.
=item texinfo_man_url_prefix
diff --git a/Pod-Simple-Texinfo/pod2texi.pl b/Pod-Simple-Texinfo/pod2texi.pl
index d992e6388f..a491662f39 100755
--- a/Pod-Simple-Texinfo/pod2texi.pl
+++ b/Pod-Simple-Texinfo/pod2texi.pl
@@ -135,6 +135,8 @@ and all the \@include is generated.");
--appendix-sections use appendix-like sections")."\n";
$pod2texi_help .= __(" --base-level=NUM|NAME level of the head1
commands; default 0")."\n";
$pod2texi_help .= __(" --debug=NUM set debugging level")."\n";
+ $pod2texi_help .= __(" --generate-setfilename generate \@setfilename for
standalone
+ manuals")."\n";
$pod2texi_help .= __(" --headings-as-sections no structuring command for
sections")."\n";
$pod2texi_help .= __(" --help display this help and
exit")."\n";
$pod2texi_help .= __(" --no-fill-section-gaps do not fill sectioning
gaps")."\n";
@@ -162,6 +164,8 @@ my $unnumbered_sections = 0;
my $appendix_sections = 0;
my $headings_as_sections = 0;
my $generate_node_menus = 0;
+# TODO change to 0 when the time has come.
+my $generate_setfilename = 1;
my $output = '-';
my $top = 'top';
my $setfilename = undef;
@@ -191,6 +195,7 @@ There is NO WARRANTY, to the extent permitted by law.\n"),
"2021";
},
'appendix-sections!' => \$appendix_sections,
'fill-section-gaps!' => \$fill_sectioning_gaps,
+ 'generate-setfilename!' => \$generate_setfilename,
'headings-as-sections!' => \$headings_as_sections,
'menus!' => \$generate_node_menus,
'output|o=s' => \$output,
@@ -477,6 +482,8 @@ foreach my $file (@input_files) {
# this sets the string that $parser's output will be sent to
$new->output_string(\$manual_texi);
+ $new->texinfo_generate_setfilename($generate_setfilename);
+
$new->texinfo_sectioning_base_level($base_level);
if ($section_nodes) {
$new->texinfo_section_nodes(1);
@@ -684,6 +691,11 @@ with output available at
L<http://www.gnu.org/software/perl/manual>.
Set debugging level to I<NUM>.
+=item B<--generate-setfilename>
+
+Generate a C<@setfilename> line for standalone manuals. Can be negated
+with C<--no-generate-setfilename>. Ignored if C<--base-level> is not 0.
+
=item B<--headings-as-sections>
Use headings commands (C<@heading>, ...) instead of the
@@ -724,8 +736,10 @@ boilerplate is a minimal beginning for a Texinfo document.
=item B<--setfilename>=I<STR>
-Use I<STR> in top boilerplate before menu and includes for C<@setfilename>.
-No C<@setfilename> is output in the default case.
+Use I<STR> in top boilerplate before menu and includes for C<@setfilename>
+for the main manual, if C<--base-level> is not set to 0. Ignored if
+C<--base-level> is 0. No C<@setfilename> is output in the default case
+for the main manual.
=item B<--subdir>=I<NAME>
diff --git a/doc/pod2texi.texi b/doc/pod2texi.texi
index f3aa26ba44..ee9f8b68fd 100644
--- a/doc/pod2texi.texi
+++ b/doc/pod2texi.texi
@@ -58,6 +58,12 @@ see @code{contrib/perldoc-all} in the Texinfo source
distribution.
Set debugging level to @emph{NUM}.
+@item @strong{@asis{}-@asis{}-@asis{}generate-setfilename}
+@anchor{pod2texi @strong{@asis{}-@asis{}-@asis{}generate-setfilename}}
+
+Generate a @code{@@setfilename} line for standalone manuals. Can be negated
+with @code{--no-generate-setfilename}. Ignored if @code{--base-level} is not
0.
+
@item @strong{@asis{}-@asis{}-@asis{}headings-as-sections}
@anchor{pod2texi @strong{@asis{}-@asis{}-@asis{}headings-as-sections}}
@@ -106,8 +112,10 @@ boilerplate is a minimal beginning for a Texinfo document.
@item @strong{@asis{}-@asis{}-@asis{}setfilename}=@emph{STR}
@anchor{pod2texi @strong{@asis{}-@asis{}-@asis{}setfilename}=@emph{STR}}
-Use @emph{STR} in top boilerplate before menu and includes for
@code{@@setfilename}.
-No @code{@@setfilename} is output in the default case.
+Use @emph{STR} in top boilerplate before menu and includes for
@code{@@setfilename}
+for the main manual, if @code{--base-level} is not set to 0. Ignored if
+@code{--base-level} is 0. No @code{@@setfilename} is output in the default
case
+for the main manual.
@item @strong{@asis{}-@asis{}-@asis{}subdir}=@emph{NAME}
@anchor{pod2texi @strong{@asis{}-@asis{}-@asis{}subdir}=@emph{NAME}}
diff --git a/man/pod2texi.1 b/man/pod2texi.1
index fd36c1e70f..368e502265 100644
--- a/man/pod2texi.1
+++ b/man/pod2texi.1
@@ -1,3 +1,4 @@
+.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man (Pod::Simple)
.\"
.\" Standard preamble:
@@ -15,29 +16,12 @@
.ft R
.fi
..
-.\" Set up some character translations and predefined strings. \*(-- will
-.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote. \*(C+ will
-.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
-.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
-.\" nothing in troff, for use with C<>.
-.tr \(*W-
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
-. ds -- \(*W-
-. ds PI pi
-. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
-. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
-. ds L" ""
-. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
-. ds -- \|\(em\|
-. ds PI \(*p
-. ds L" ``
-. ds R" ''
. ds C`
. ds C'
'br\}
@@ -68,84 +52,22 @@
. \}
.\}
.rr rF
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
-.\" Fear. Run. Save yourself. No user-serviceable parts.
-. \" fudge factors for nroff and troff
-.if n \{\
-. ds #H 0
-. ds #V .8m
-. ds #F .3m
-. ds #[ \f1
-. ds #] \fP
-.\}
-.if t \{\
-. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
-. ds #V .6m
-. ds #F 0
-. ds #[ \&
-. ds #] \&
-.\}
-. \" simple accents for nroff and troff
-.if n \{\
-. ds ' \&
-. ds ` \&
-. ds ^ \&
-. ds , \&
-. ds ~ ~
-. ds /
-.\}
-.if t \{\
-. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
-. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
-. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
-. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
-. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
-. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
-.\}
-. \" troff and (daisy-wheel) nroff accents
-.ds :
\\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
-.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
-.ds o
\\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
-.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
-.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
-.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
-.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
-.ds ae a\h'-(\w'a'u*4/10)'e
-.ds Ae A\h'-(\w'A'u*4/10)'E
-. \" corrections for vroff
-.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
-.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
-. \" for low resolution devices (crt and lpr)
-.if \n(.H>23 .if \n(.V>19 \
-\{\
-. ds : e
-. ds 8 ss
-. ds o a
-. ds d- d\h'-1'\(ga
-. ds D- D\h'-1'\(hy
-. ds th \o'bp'
-. ds Th \o'LP'
-. ds ae ae
-. ds Ae AE
-.\}
-.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "POD2TEXI 1"
-.TH POD2TEXI 1 "2024-01-06" "perl" "User Contributed Perl Documentation"
+.TH POD2TEXI 1 2024-04-17 perl "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
-.SH "NAME"
+.SH NAME
pod2texi \- convert Pod to Texinfo
-.SH "SYNOPSIS"
+.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& pod2texi [OPTION]... POD...
.Ve
-.SH "DESCRIPTION"
+.SH DESCRIPTION
.IX Header "DESCRIPTION"
Translate Pod file(s) to Texinfo. There are two basic modes of
operation. First, by default, each Pod is translated to a standalone
@@ -154,14 +76,14 @@ Texinfo manual.
Second, if \f(CW\*(C`\-\-base\-level\*(C'\fR is set higher than 0, each Pod is
translated
to a file suitable for \f(CW@include\fR, and one more file with a main menu
and all the \f(CW@include\fR is generated.
-.SH "OPTIONS"
+.SH OPTIONS
.IX Header "OPTIONS"
-.IP "\fB\-\-appendix\-sections\fR" 4
+.IP \fB\-\-appendix\-sections\fR 4
.IX Item "--appendix-sections"
Use appendix sectioning commands (\f(CW@appendix\fR, ...) instead of the
default numbered sectioning Texinfo @\-commands (\f(CW@chapter\fR,
\&\f(CW@section\fR, ...).
-.IP "\fB\-\-base\-level\fR=\fINUM|NAME\fR" 4
+.IP \fB\-\-base\-level\fR=\fINUM|NAME\fR 4
.IX Item "--base-level=NUM|NAME"
Sets the level of the \f(CW\*(C`head1\*(C'\fR commands. It may be an integer
or a
Texinfo sectioning command (without the \f(CW\*(C`@\*(C'\fR): 1 corresponds to
the
@@ -177,57 +99,63 @@ chapter in a large manual, you should use
\f(CW\*(C`section\*(C'\fR as the base
.Sp
For an example of making Texinfo out of the Perl documentation itself,
see \f(CW\*(C`contrib/perldoc\-all\*(C'\fR in the Texinfo source distribution.
-.IP "\fB\-\-debug\fR=\fI\s-1NUM\s0\fR" 4
+.IP \fB\-\-debug\fR=\fINUM\fR 4
.IX Item "--debug=NUM"
-Set debugging level to \fI\s-1NUM\s0\fR.
-.IP "\fB\-\-headings\-as\-sections\fR" 4
+Set debugging level to \fINUM\fR.
+.IP \fB\-\-generate\-setfilename\fR 4
+.IX Item "--generate-setfilename"
+Generate a \f(CW@setfilename\fR line for standalone manuals. Can be negated
+with \f(CW\*(C`\-\-no\-generate\-setfilename\*(C'\fR. Ignored if
\f(CW\*(C`\-\-base\-level\*(C'\fR is not 0.
+.IP \fB\-\-headings\-as\-sections\fR 4
.IX Item "--headings-as-sections"
Use headings commands (\f(CW@heading\fR, ...) instead of the
default numbered sectioning Texinfo @\-commands (\f(CW@chapter\fR,
\&\f(CW@section\fR, ...). The sectioning command covering the entire
file output for each Pod file if \fB\-\-base\-level\fR is not 0 is a
numbered command.
-.IP "\fB\-\-help\fR" 4
+.IP \fB\-\-help\fR 4
.IX Item "--help"
Display help and exit.
-.IP "\fB\-\-menus\fR" 4
+.IP \fB\-\-menus\fR 4
.IX Item "--menus"
Output node menus. If there is a main manual, its Top node menu
is always output, since a master menu is generated. Other nodes
menus are not output in the default case.
-.IP "\fB\-\-output\fR=\fI\s-1NAME\s0\fR" 4
+.IP \fB\-\-output\fR=\fINAME\fR 4
.IX Item "--output=NAME"
Name for the first manual, or the main manual if there is a main manual.
Default is to write to standard output.
-.IP "\fB\-\-no\-section\-nodes\fR" 4
+.IP \fB\-\-no\-section\-nodes\fR 4
.IX Item "--no-section-nodes"
Use anchors for sections instead of nodes.
-.IP "\fB\-\-no\-fill\-section\-gaps\fR" 4
+.IP \fB\-\-no\-fill\-section\-gaps\fR 4
.IX Item "--no-fill-section-gaps"
Do not fill sectioning gaps with empty \f(CW@unnumbered\fR files.
Ordinarily, it's good to keep the sectioning hierarchy intact.
-.IP "\fB\-\-preamble\fR=\fI\s-1STR\s0\fR" 4
+.IP \fB\-\-preamble\fR=\fISTR\fR 4
.IX Item "--preamble=STR"
-Insert \fI\s-1STR\s0\fR as top boilerplate before menu and includes. If
\fI\s-1STR\s0\fR is
+Insert \fISTR\fR as top boilerplate before menu and includes. If \fISTR\fR is
set to \f(CW\*(C`\-\*(C'\fR, read the top boilerplate from the standard input.
The default top
boilerplate is a minimal beginning for a Texinfo document.
-.IP "\fB\-\-setfilename\fR=\fI\s-1STR\s0\fR" 4
+.IP \fB\-\-setfilename\fR=\fISTR\fR 4
.IX Item "--setfilename=STR"
-Use \fI\s-1STR\s0\fR in top boilerplate before menu and includes for
\f(CW@setfilename\fR.
-No \f(CW@setfilename\fR is output in the default case.
-.IP "\fB\-\-subdir\fR=\fI\s-1NAME\s0\fR" 4
+Use \fISTR\fR in top boilerplate before menu and includes for
\f(CW@setfilename\fR
+for the main manual, if \f(CW\*(C`\-\-base\-level\*(C'\fR is not set to 0.
Ignored if
+\&\f(CW\*(C`\-\-base\-level\*(C'\fR is 0. No \f(CW@setfilename\fR is output
in the default case
+for the main manual.
+.IP \fB\-\-subdir\fR=\fINAME\fR 4
.IX Item "--subdir=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
\fI\s-1NAME\s0\fR.
-.IP "\fB\-\-unnumbered\-sections\fR" 4
+an input Pod file), then those include files are put in directory \fINAME\fR.
+.IP \fB\-\-unnumbered\-sections\fR 4
.IX Item "--unnumbered-sections"
Use unnumbered sectioning commands (\f(CW@unnumbered\fR, ...) instead of the
default numbered sectioning Texinfo @\-commands (\f(CW@chapter\fR,
\&\f(CW@section\fR, ...).
-.IP "\fB\-\-top\fR=\fI\s-1TOP\s0\fR" 4
+.IP \fB\-\-top\fR=\fITOP\fR 4
.IX Item "--top=TOP"
Name of the \f(CW@top\fR element for the main manual. May contain Texinfo
code.
-.IP "\fB\-\-version\fR" 4
+.IP \fB\-\-version\fR 4
.IX Item "--version"
Display version information and exit.
.SH "SEE ALSO"
@@ -236,14 +164,14 @@ Pod::Simple::Texinfo. perlpod. The Texinfo manual.
Texinfo home page: <https://www.gnu.org/software/texinfo/>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
-Copyright 2012\-2023 Free Software Foundation, Inc.
+Copyright 2012\-2024 Free Software Foundation, Inc.
.PP
This program is free software; you can redistribute it and/or modify
-it under the terms of the \s-1GNU\s0 General Public License as published by
+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.
.PP
-There is \s-1NO WARRANTY,\s0 to the extent permitted by law.
-.SH "AUTHOR"
+There is NO WARRANTY, to the extent permitted by law.
+.SH AUTHOR
.IX Header "AUTHOR"
Patrice Dumas <bug\-texinfo@gnu.org>.