Debian Codegraph @

upstream/debian-unstable/man1/pod2texi.1

raw
1 .\" Automatically generated by Pod::Man (Pod::Simple)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C` ""
34 . ds C' ""
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 . ds C`
42 . ds C'
43 'br\}
44 .\"
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
46 .ie \n(.g .ds Aq \(aq
47 .el .ds Aq '
48 .\"
49 .\" If the F register is >0, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
53 .\"
54 .\" Avoid warning from groff about undefined register 'F'.
55 .de IX
56 ..
57 .nr rF 0
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{\
60 . if \nF \{\
61 . de IX
62 . tm Index:\\$1\t\\n%\t"\\$2"
63 ..
64 . if !\nF==2 \{\
65 . nr % 0
66 . nr F 2
67 . \}
68 . \}
69 .\}
70 .rr rF
71 .\"
72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
73 .\" Fear. Run. Save yourself. No user-serviceable parts.
74 . \" fudge factors for nroff and troff
75 .if n \{\
76 . ds #H 0
77 . ds #V .8m
78 . ds #F .3m
79 . ds #[ \f1
80 . ds #] \fP
81 .\}
82 .if t \{\
83 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
84 . ds #V .6m
85 . ds #F 0
86 . ds #[ \&
87 . ds #] \&
88 .\}
89 . \" simple accents for nroff and troff
90 .if n \{\
91 . ds ' \&
92 . ds ` \&
93 . ds ^ \&
94 . ds , \&
95 . ds ~ ~
96 . ds /
97 .\}
98 .if t \{\
99 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
100 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
101 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
102 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
103 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
104 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105 .\}
106 . \" troff and (daisy-wheel) nroff accents
107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
114 .ds ae a\h'-(\w'a'u*4/10)'e
115 .ds Ae A\h'-(\w'A'u*4/10)'E
116 . \" corrections for vroff
117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
119 . \" for low resolution devices (crt and lpr)
120 .if \n(.H>23 .if \n(.V>19 \
121 \{\
122 . ds : e
123 . ds 8 ss
124 . ds o a
125 . ds d- d\h'-1'\(ga
126 . ds D- D\h'-1'\(hy
127 . ds th \o'bp'
128 . ds Th \o'LP'
129 . ds ae ae
130 . ds Ae AE
131 .\}
132 .rm #[ #] #H #V #F C
133 .\" ========================================================================
134 .\"
135 .IX Title "POD2TEXI 1"
136 .TH POD2TEXI 1 "2025-01-09" "perl" "User Contributed Perl Documentation"
137 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
138 .\" way too many mistakes in technical documents.
139 .if n .ad l
140 .nh
141 .SH "NAME"
142 pod2texi \- convert Pod to Texinfo
143 .SH "SYNOPSIS"
144 .IX Header "SYNOPSIS"
145 .Vb 1
146 \& pod2texi [OPTION]... POD...
147 .Ve
148 .SH "DESCRIPTION"
149 .IX Header "DESCRIPTION"
150 Translate Pod file(s) to Texinfo. There are two basic modes of
151 operation. First, by default, each Pod is translated to a standalone
152 Texinfo manual.
153 .PP
154 Second, if \f(CW\*(C`\-\-base\-level\*(C'\fR is set higher than 0, each Pod is translated
155 to a file suitable for \f(CW@include\fR, and one more file with a main menu
156 and all the \f(CW@include\fR is generated.
157 .SH "OPTIONS"
158 .IX Header "OPTIONS"
159 .IP "\fB\-\-appendix\-sections\fR" 4
160 .IX Item "--appendix-sections"
161 Use appendix sectioning commands (\f(CW@appendix\fR, ...) instead of the
162 default numbered sectioning Texinfo @\-commands (\f(CW@chapter\fR,
163 \&\f(CW@section\fR, ...).
164 .IP "\fB\-\-base\-level\fR=\fINUM|NAME\fR" 4
165 .IX Item "--base-level=NUM|NAME"
166 Sets the level of the \f(CW\*(C`head1\*(C'\fR commands. It may be an integer or a
167 Texinfo sectioning command (without the \f(CW\*(C`@\*(C'\fR): 1 corresponds to the
168 \&\f(CW@chapter\fR/\f(CW@unnumbered\fR level, 2 to the \f(CW@section\fR level, and so on.
169 The default is 0, meaning that \f(CW\*(C`head1\*(C'\fR commands are still output as
170 chapters, but the output is arranged as a standalone manual.
171 .Sp
172 If the level is not 0, the Pod file is rendered as a fragment of a
173 Texinfo manual suitable for \f(CW@include\fR. In this case, each Pod file
174 has an additional sectioning command covering the entire file, one level
175 above the \f(CW\*(C`\-\-base\-level\*(C'\fR value. Therefore, to make each Pod file a
176 chapter in a large manual, you should use \f(CW\*(C`section\*(C'\fR as the base level.
177 .Sp
178 For an example of making Texinfo out of the Perl documentation itself,
179 see \f(CW\*(C`contrib/perldoc\-all\*(C'\fR in the Texinfo source distribution.
180 .IP "\fB\-\-debug\fR=\fI\s-1NUM\s0\fR" 4
181 .IX Item "--debug=NUM"
182 Set debugging level to \fI\s-1NUM\s0\fR.
183 .IP "\fB\-\-generate\-setfilename\fR" 4
184 .IX Item "--generate-setfilename"
185 Generate a \f(CW@setfilename\fR line for standalone manuals. Can be negated
186 with \f(CW\*(C`\-\-no\-generate\-setfilename\*(C'\fR. Ignored if \f(CW\*(C`\-\-base\-level\*(C'\fR is not 0.
187 .IP "\fB\-\-headings\-as\-sections\fR" 4
188 .IX Item "--headings-as-sections"
189 Use headings commands (\f(CW@heading\fR, ...) instead of the
190 default numbered sectioning Texinfo @\-commands (\f(CW@chapter\fR,
191 \&\f(CW@section\fR, ...). The sectioning command covering the entire
192 file output for each Pod file if \fB\-\-base\-level\fR is not 0 is a
193 numbered command.
194 .IP "\fB\-\-help\fR" 4
195 .IX Item "--help"
196 Display help and exit.
197 .IP "\fB\-\-menus\fR" 4
198 .IX Item "--menus"
199 Output node menus. If there is a main manual, its Top node menu
200 is always output, since a master menu is generated. Other nodes
201 menus are not output in the default case.
202 .IP "\fB\-\-outdir\fR=\fI\s-1NAME\s0\fR" 4
203 .IX Item "--outdir=NAME"
204 If there is a main manual with include files (each corresponding to
205 an input Pod file), then the generated Texinfo files are put in
206 directory \fI\s-1NAME\s0\fR. Default is based on \f(CW\*(C`\-\-subdir\*(C'\fR.
207 .IP "\fB\-\-output\fR=\fI\s-1NAME\s0\fR" 4
208 .IX Item "--output=NAME"
209 Name for the first manual, or the main manual if there is a main manual.
210 Default is to write to standard output.
211 .IP "\fB\-\-no\-section\-nodes\fR" 4
212 .IX Item "--no-section-nodes"
213 Use anchors for sections instead of nodes.
214 .IP "\fB\-\-no\-fill\-section\-gaps\fR" 4
215 .IX Item "--no-fill-section-gaps"
216 Do not fill sectioning gaps with empty \f(CW@unnumbered\fR files.
217 Ordinarily, it's good to keep the sectioning hierarchy intact.
218 .IP "\fB\-\-preamble\fR=\fI\s-1STR\s0\fR" 4
219 .IX Item "--preamble=STR"
220 Insert \fI\s-1STR\s0\fR as top boilerplate before menu and includes. If \fI\s-1STR\s0\fR is
221 set to \f(CW\*(C`\-\*(C'\fR, read the top boilerplate from the standard input. The default top
222 boilerplate is a minimal beginning for a Texinfo document.
223 .IP "\fB\-\-setfilename\fR=\fI\s-1STR\s0\fR" 4
224 .IX Item "--setfilename=STR"
225 Use \fI\s-1STR\s0\fR in top boilerplate before menu and includes for \f(CW@setfilename\fR
226 for the main manual, if \f(CW\*(C`\-\-base\-level\*(C'\fR is not set to 0. Ignored if
227 \&\f(CW\*(C`\-\-base\-level\*(C'\fR is 0. No \f(CW@setfilename\fR is output in the default case
228 for the main manual.
229 .IP "\fB\-\-subdir\fR=\fI\s-1NAME\s0\fR" 4
230 .IX Item "--subdir=NAME"
231 If there is a main manual with include files (each corresponding to
232 an input Pod file), then those include files are included from \fI\s-1NAME\s0\fR.
233 .Sp
234 If \f(CW\*(C`\-\-outdir\*(C'\fR is set, \fI\s-1NAME\s0\fR should in general be set to the relative
235 directory between the main manual and \f(CW\*(C`\-\-outdir\*(C'\fR argument.
236 .IP "\fB\-\-unnumbered\-sections\fR" 4
237 .IX Item "--unnumbered-sections"
238 Use unnumbered sectioning commands (\f(CW@unnumbered\fR, ...) instead of the
239 default numbered sectioning Texinfo @\-commands (\f(CW@chapter\fR,
240 \&\f(CW@section\fR, ...).
241 .IP "\fB\-\-top\fR=\fI\s-1TOP\s0\fR" 4
242 .IX Item "--top=TOP"
243 Name of the \f(CW@top\fR element for the main manual. May contain Texinfo code.
244 .IP "\fB\-\-version\fR" 4
245 .IX Item "--version"
246 Display version information and exit.
247 .SH "SEE ALSO"
248 .IX Header "SEE ALSO"
249 Pod::Simple::Texinfo. perlpod. The Texinfo manual.
250 Texinfo home page: <https://www.gnu.org/software/texinfo/>
251 .SH "COPYRIGHT AND LICENSE"
252 .IX Header "COPYRIGHT AND LICENSE"
253 Copyright 2012\-2026 Free Software Foundation, Inc.
254 .PP
255 This program is free software; you can redistribute it and/or modify
256 it under the terms of the \s-1GNU\s0 General Public License as published by
257 the Free Software Foundation; either version 3 of the License,
258 or (at your option) any later version.
259 .PP
260 There is \s-1NO WARRANTY,\s0 to the extent permitted by law.
261 .SH "AUTHOR"
262 .IX Header "AUTHOR"
263 Patrice Dumas <bug\[email protected]>.